domain-search-mcp 1.2.7 → 1.2.9

package/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Development Commands
+
+```bash
+npm run build      # Compile TypeScript to dist/
+npm run dev        # Watch mode with tsx
+npm start          # Run compiled server
+npm test           # Run all tests
+npm run test:unit  # Run unit tests only
+npm run coverage   # Run tests with coverage
+```
+
+Run a single test file:
+```bash
+npx jest tests/unit/cache.test.ts
+npx jest --testPathPattern="validators"
+```
+
+## Architecture Overview
+
+This is an MCP (Model Context Protocol) server for domain availability searches. It aggregates data from multiple registrars and fallback sources.
+
+### Core Flow
+
+```
+server.ts (MCP Server)
+    ↓
+tools/*.ts (Tool definitions + executors)
+    ↓
+services/domain-search.ts (Orchestration layer)
+    ↓
+registrars/*.ts (API adapters) → Porkbun, Namecheap, GoDaddy
+    or
+fallbacks/*.ts (RDAP, WHOIS)
+```
+
+### Key Components
+
+**Tools** (`src/tools/`): Each MCP tool has three exports:
+- `*Tool`: Tool definition (name, description, schema)
+- `*Schema`: Zod validation schema
+- `execute*`: Execution function
+
+**Registrar Adapters** (`src/registrars/`): All extend `RegistrarAdapter` base class which provides:
+- Token bucket rate limiting
+- Retry with exponential backoff
+- Timeout handling
+- Standardized `DomainResult` creation
+
+**Domain Search Service** (`src/services/domain-search.ts`): Orchestrates source selection:
+1. Porkbun API (if configured)
+2. Namecheap API (if configured)
+3. GoDaddy MCP (always available, no auth)
+4. RDAP fallback
+5. WHOIS last resort
+
+**Utilities** (`src/utils/`):
+- `cache.ts`: TTL-based in-memory cache
+- `errors.ts`: Structured error types with retry hints
+- `premium-analyzer.ts`: Domain quality scoring and premium detection
+- `semantic-engine.ts`: AI-powered domain name generation
+
+### Type System
+
+Core types in `src/types.ts`:
+- `DomainResult`: Complete domain availability/pricing info
+- `SearchResponse`: Results + insights + next_steps
+- `DataSource`: Enum of where data came from
+- `Config`: Environment configuration shape
+
+### Configuration
+
+Server works without API keys (falls back to RDAP/WHOIS). For pricing data, configure in `.env`:
+- `PORKBUN_API_KEY` + `PORKBUN_API_SECRET`: Fast with pricing
+- `NAMECHEAP_API_KEY` + `NAMECHEAP_API_USER`: Requires IP whitelist
+
+### Adding a New Tool
+
+1. Create `src/tools/new_tool.ts` with schema, tool definition, and executor
+2. Export from `src/tools/index.ts`
+3. Add to `TOOLS` array and `executeToolCall` switch in `server.ts`
+
+### Adding a New Registrar
+
+1. Create `src/registrars/new_registrar.ts` extending `RegistrarAdapter`
+2. Implement `search()`, `getTldInfo()`, `isEnabled()`
+3. Export from `src/registrars/index.ts`
+4. Add to source selection logic in `services/domain-search.ts`

package/README.md

@@ -3595,7 +3595,386 @@ function formatReportForPresentation(report: AcquisitionReport): string {
 // Usage example
 const report = await completeDomainAcquisition("techstartup");
 console.log(report.presentation);
+```
+
+#### Finalized Brand Acquisition Wrapper
+
+Production-ready wrapper with explicit workflow orchestration and edge case handling:
+
+```typescript
+import { searchDomain, checkSocials, suggestDomains, compareRegistrars } from 'domain-search-mcp';
+
+/**
+ * FINALIZED BRAND ACQUISITION WORKFLOW
+ *
+ * Integrates search_domain, check_socials, and suggest_domains in a single
+ * coordinated workflow with comprehensive edge case handling.
+ *
+ * Workflow Steps:
+ * 1. Parallel domain + social checks with coordinated timeouts
+ * 2. Handle partial availability (some domains available, some not)
+ * 3. Generate alternatives for unavailable domains
+ * 4. Compare pricing across registrars
+ * 5. Compile actionable report
+ */
+async function brandAcquisitionWorkflow(
+  brandName: string,
+  options: {
+    tlds?: string[];
+    socialPlatforms?: string[];
+    timeoutMs?: number;
+    maxRetries?: number;
+  } = {}
+): Promise<BrandAcquisitionResult> {
+  const {
+    tlds = ["com", "io", "dev", "app", "co"],
+    socialPlatforms = ["github", "twitter", "instagram", "npm", "linkedin"],
+    timeoutMs = 15000,
+    maxRetries = 3
+  } = options;
+
+  const startTime = Date.now();
+  const errors: WorkflowError[] = [];
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // STEP 1: Simultaneous Platform Checking with Coordinated Timeouts
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  // Create AbortController for coordinated timeout across all parallel checks
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    // Run domain and social checks in parallel with shared timeout
+    const [domainOutcome, socialOutcome] = await Promise.allSettled([
+      // Domain check with per-TLD timeout handling
+      executeWithTimeout(
+        searchDomain({ domain_name: brandName, tlds }),
+        timeoutMs * 0.8,  // 80% of total timeout for domains
+        "domain_search"
+      ),
+      // Social check with platform-specific handling
+      executeWithTimeout(
+        checkSocials({ name: brandName, platforms: socialPlatforms }),
+        timeoutMs * 0.8,  // 80% of total timeout for socials
+        "social_check"
+      )
+    ]);
+
+    clearTimeout(timeoutId);
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STEP 2: Handle Partial Availability Scenarios
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    // Process domain results with partial failure handling
+    let domainResults: DomainResult[] = [];
+    if (domainOutcome.status === "fulfilled") {
+      domainResults = domainOutcome.value.results;
+    } else {
+      errors.push({
+        stage: "domain_search",
+        error: domainOutcome.reason?.message || "Domain search failed",
+        recoverable: true,
+        fallback: "Will retry individual TLDs"
+      });
+
+      // Fallback: Try each TLD individually
+      domainResults = await retryIndividualTlds(brandName, tlds, maxRetries);
+    }
+
+    // Categorize domain results
+    const availableDomains = domainResults.filter(r => r.available === true);
+    const takenDomains = domainResults.filter(r => r.available === false);
+    const failedDomains = domainResults.filter(r => r.error);
+
+    // Process social results with per-platform handling
+    let socialResults: SocialResult[] = [];
+    if (socialOutcome.status === "fulfilled") {
+      socialResults = socialOutcome.value.platforms || socialOutcome.value.results;
+    } else {
+      errors.push({
+        stage: "social_check",
+        error: socialOutcome.reason?.message || "Social check failed",
+        recoverable: true,
+        fallback: "Manual verification required for all platforms"
+      });
+
+      // Provide manual verification links for all platforms
+      socialResults = socialPlatforms.map(platform => ({
+        platform,
+        available: null,
+        confidence: "unverified",
+        manual_check_url: getSocialProfileUrl(platform, brandName),
+        error: "Automated check failed"
+      }));
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STEP 3: Generate Alternatives for Unavailable Domains
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    let alternatives: DomainSuggestion[] = [];
+
+    // Only generate alternatives if primary .com is taken
+    const comAvailable = availableDomains.some(d => d.domain.endsWith('.com'));
+    if (!comAvailable && takenDomains.some(d => d.domain.endsWith('.com'))) {
+      try {
+        const suggestions = await suggestDomains({
+          base_name: brandName,
+          tld: "com",
+          max_suggestions: 10,
+          variants: ["prefixes", "suffixes", "hyphen"]
+        });
+        alternatives = suggestions.suggestions.filter(s => s.available);
+      } catch (error) {
+        errors.push({
+          stage: "suggest_domains",
+          error: error.message,
+          recoverable: false,
+          fallback: "No alternatives generated"
+        });
+      }
+    }
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STEP 4: Compare Pricing for Available Domains
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    const pricingComparisons = await Promise.allSettled(
+      availableDomains.slice(0, 5).map(async (d) => {
+        const [name, tld] = d.domain.split('.');
+        const comparison = await compareRegistrars({ domain: name, tld });
+        return { domain: d.domain, comparison };
+      })
+    );
+
+    const pricing = pricingComparisons
+      .filter((p): p is PromiseFulfilledResult<any> => p.status === "fulfilled")
+      .map(p => p.value);
+
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STEP 5: Compile Final Report
+    // ═══════════════════════════════════════════════════════════════════════════
+
+    const executionTime = Date.now() - startTime;
+
+    return {
+      success: errors.length === 0,
+      brandName,
+      executionTime,
+
+      // Domain availability summary
+      domains: {
+        available: availableDomains.map(d => ({
+          domain: d.domain,
+          price: d.price_first_year,
+          registrar: d.registrar,
+          bestPrice: pricing.find(p => p.domain === d.domain)?.comparison?.best_first_year
+        })),
+        taken: takenDomains.map(d => d.domain),
+        failed: failedDomains.map(d => ({ domain: d.domain, error: d.error })),
+        alternatives: alternatives
+      },
+
+      // Social media summary with confidence levels
+      socials: {
+        available: socialResults.filter(s => s.available === true),
+        taken: socialResults.filter(s => s.available === false),
+        unverified: socialResults.filter(s => s.available === null),
+        highConfidence: socialResults.filter(s => s.confidence === "high"),
+        needsManualCheck: socialResults.filter(s =>
+          s.confidence === "low" || s.confidence === "unverified"
+        )
+      },
+
+      // Actionable recommendations
+      recommendations: generateRecommendations(
+        availableDomains,
+        takenDomains,
+        socialResults,
+        alternatives,
+        pricing
+      ),
+
+      // Error tracking for debugging
+      errors,
+
+      // Partial success indicator
+      partialSuccess: errors.length > 0 && (availableDomains.length > 0 || socialResults.length > 0)
+    };
+
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// EDGE CASE HANDLING UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Execute a promise with timeout, returning a structured result
+ */
+async function executeWithTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  operationName: string
+): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) =>
+      setTimeout(
+        () => reject(new Error(`${operationName} timed out after ${timeoutMs}ms`)),
+        timeoutMs
+      )
+    )
+  ]);
+}
+
+/**
+ * Retry individual TLDs when bulk search fails
+ * Implements staggered retry to avoid rate limiting
+ */
+async function retryIndividualTlds(
+  brandName: string,
+  tlds: string[],
+  maxRetries: number
+): Promise<DomainResult[]> {
+  const results: DomainResult[] = [];
+
+  for (const tld of tlds) {
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        // Stagger requests to avoid rate limiting
+        if (attempt > 1) {
+          await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt - 1)));
+        }
+
+        const result = await searchDomain({
+          domain_name: brandName,
+          tlds: [tld]
+        });
+
+        if (result.results[0]) {
+          results.push(result.results[0]);
+          break;
+        }
+      } catch (error) {
+        lastError = error;
+        if (attempt === maxRetries) {
+          results.push({
+            domain: `${brandName}.${tld}`,
+            available: null,
+            error: lastError.message,
+            source: "retry_failed"
+          });
+        }
+      }
+    }
+  }
 
+  return results;
+}
+
+/**
+ * Get social profile URL for manual verification
+ */
+function getSocialProfileUrl(platform: string, username: string): string {
+  const urls: Record<string, string> = {
+    github: `https://github.com/${username}`,
+    twitter: `https://twitter.com/${username}`,
+    instagram: `https://instagram.com/${username}`,
+    linkedin: `https://linkedin.com/company/${username}`,
+    npm: `https://npmjs.com/~${username}`,
+    tiktok: `https://tiktok.com/@${username}`,
+    reddit: `https://reddit.com/user/${username}`
+  };
+  return urls[platform] || `https://${platform}.com/${username}`;
+}
+
+/**
+ * Generate actionable recommendations based on results
+ */
+function generateRecommendations(
+  available: DomainResult[],
+  taken: DomainResult[],
+  socials: SocialResult[],
+  alternatives: DomainSuggestion[],
+  pricing: any[]
+): string[] {
+  const recommendations: string[] = [];
+
+  // Domain recommendations
+  if (available.length > 0) {
+    const cheapest = available.sort((a, b) =>
+      (a.price_first_year || 999) - (b.price_first_year || 999)
+    )[0];
+    recommendations.push(
+      `Register ${cheapest.domain} ($${cheapest.price_first_year}/yr) - best value`
+    );
+  } else if (alternatives.length > 0) {
+    recommendations.push(
+      `Primary domains taken. Top alternative: ${alternatives[0].domain}`
+    );
+  }
+
+  // Social media recommendations
+  const availableSocials = socials.filter(s => s.available === true);
+  const takenSocials = socials.filter(s => s.available === false);
+
+  if (availableSocials.length > 0) {
+    recommendations.push(
+      `Secure handles on: ${availableSocials.map(s => s.platform).join(", ")}`
+    );
+  }
+
+  if (takenSocials.length > 0) {
+    recommendations.push(
+      `Consider alternative usernames for: ${takenSocials.map(s => s.platform).join(", ")}`
+    );
+  }
+
+  // Manual verification recommendations
+  const needsManual = socials.filter(s => s.confidence === "low" || s.available === null);
+  if (needsManual.length > 0) {
+    recommendations.push(
+      `Manually verify: ${needsManual.map(s => s.platform).join(", ")}`
+    );
+  }
+
+  return recommendations;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// USAGE EXAMPLE
+// ═══════════════════════════════════════════════════════════════════════════
+
+const result = await brandAcquisitionWorkflow("nexatech", {
+  tlds: ["com", "io", "dev"],
+  socialPlatforms: ["github", "twitter", "npm"],
+  timeoutMs: 10000,
+  maxRetries: 2
+});
+
+console.log(`Brand: ${result.brandName}`);
+console.log(`Success: ${result.success}`);
+console.log(`Execution time: ${result.executionTime}ms`);
+console.log(`Available domains: ${result.domains.available.length}`);
+console.log(`Available socials: ${result.socials.available.length}`);
+console.log(`Recommendations:`, result.recommendations);
+
+// Handle partial success
+if (result.partialSuccess) {
+  console.log("⚠️ Partial success - some checks failed:");
+  result.errors.forEach(e => console.log(`  - ${e.stage}: ${e.error}`));
+}
+```
+
+**Example output:**
+```
 // Example output:
 // ════════════════════════════════════════════════════════════
 //   BRAND VALIDATION REPORT: TECHSTARTUP
@@ -4424,6 +4803,762 @@ async function domainResearchPipeline(businessIdea: string) {
 const research = await domainResearchPipeline("ai-powered code review tool");
 ```
 
+#### Tool Parameter Optimization Reference
+
+Quick reference table for optimizing each tool based on startup context:
+
+| Tool | Parameter | Tech Startup | E-commerce | Creative | Fintech |
+|------|-----------|--------------|------------|----------|---------|
+| **search_domain** | `tlds` | `["io","dev","app"]` | `["com","co","shop"]` | `["design","studio","io"]` | `["com","io","finance"]` |
+| **tld_info** | `detailed` | `true` (need restrictions) | `false` (basic info) | `true` (pricing focus) | `true` (compliance check) |
+| **suggest_domains** | `style` | `"brandable"` | `"brandable"` | `"creative"` | `"brandable"` |
+| **suggest_domains** | `industry` | `"tech"` | `"ecommerce"` | `"creative"` | `"finance"` |
+| **suggest_domains** | `max_suggestions` | `15-20` | `10-15` | `20-25` | `10` |
+| **check_socials** | `platforms` | `["github","npm","twitter"]` | `["instagram","tiktok"]` | `["instagram","dribbble"]` | `["linkedin","twitter"]` |
+| **compare_registrars** | Priority | Performance | Best price | Design focus | Security |
+
+#### Direct tld_info Usage for Startup Research
+
+The `tld_info` tool provides critical context for startup domain decisions. Use it directly to gather TLD-specific insights:
+
+```typescript
+import { tldInfo } from 'domain-search-mcp';
+
+// Example: Get detailed TLD information for tech startup decision-making
+async function analyzeTldsForStartup(startupType: string) {
+  // Define TLDs relevant to startup type
+  const tldsByType = {
+    tech: ["io", "dev", "app", "sh", "ai"],
+    ecommerce: ["com", "shop", "store", "co"],
+    creative: ["design", "studio", "art", "io"],
+    fintech: ["com", "io", "finance", "money"]
+  };
+
+  const tldsToAnalyze = tldsByType[startupType] || tldsByType.tech;
+  const analysis = [];
+
+  // Fetch detailed info for each TLD using tld_info directly
+  for (const tld of tldsToAnalyze) {
+    const info = await tldInfo({ tld, detailed: true });
+
+    analysis.push({
+      tld: info.tld,
+      description: info.description,
+      priceRange: {
+        min: info.price_range.min,
+        max: info.price_range.max,
+        currency: "USD"
+      },
+      typicalUse: info.typical_use,
+      popularity: info.popularity,
+      restrictions: info.restrictions || [],
+      recommendation: info.recommendation,
+      // Calculate suitability score based on startup type
+      suitabilityScore: calculateTldSuitability(info, startupType)
+    });
+  }
+
+  // Sort by suitability score
+  return analysis.sort((a, b) => b.suitabilityScore - a.suitabilityScore);
+}
+
+function calculateTldSuitability(tldData: TldInfoResult, startupType: string): number {
+  let score = 50; // Base score
+
+  // Price factor
+  if (tldData.price_range.min < 15) score += 20;
+  else if (tldData.price_range.min < 30) score += 10;
+
+  // Popularity factor
+  if (tldData.popularity === "Very High") score += 15;
+  else if (tldData.popularity === "High") score += 10;
+
+  // Startup type specific bonuses
+  if (startupType === "tech" && ["io", "dev", "app"].includes(tldData.tld)) score += 15;
+  if (startupType === "ecommerce" && tldData.tld === "com") score += 20;
+  if (startupType === "creative" && ["design", "studio"].includes(tldData.tld)) score += 15;
+
+  // Restriction penalty
+  if (tldData.restrictions && tldData.restrictions.length > 0) score -= 10;
+
+  return Math.min(100, Math.max(0, score));
+}
+
+// Usage
+const tldAnalysis = await analyzeTldsForStartup("tech");
+console.log("TLD Analysis for Tech Startup:");
+tldAnalysis.forEach(tld => {
+  console.log(`  .${tld.tld}: Score ${tld.suitabilityScore}/100`);
+  console.log(`    ${tld.description}`);
+  console.log(`    Price: $${tld.priceRange.min}-$${tld.priceRange.max}/yr`);
+});
+
+// Output:
+// TLD Analysis for Tech Startup:
+//   .io: Score 85/100
+//     Popular with tech startups and SaaS companies
+//     Price: $32-$44/yr
+//   .dev: Score 80/100
+//     Google-operated TLD for developers
+//     Price: $12-$16/yr
+//   .app: Score 75/100
+//     Mobile and web applications
+//     Price: $14-$18/yr
+```
+
+#### Startup-Type Optimized Parameters
+
+Different startup types require different tool parameter configurations for optimal results:
+
+```typescript
+// Startup type definitions with optimized tool parameters
+const STARTUP_TYPE_CONFIGS = {
+  tech: {
+    // Tech startups: developer tools, SaaS, APIs
+    tlds: ["io", "dev", "app", "com", "sh"],
+    suggestStyle: "brandable" as const,
+    socialPlatforms: ["github", "twitter", "npm", "pypi", "producthunt"],
+    priceThreshold: 50,  // Tech startups accept higher TLD costs
+    industryHint: "tech" as const
+  },
+  ecommerce: {
+    // E-commerce: retail, marketplace, DTC brands
+    tlds: ["com", "co", "shop", "store", "io"],
+    suggestStyle: "brandable" as const,
+    socialPlatforms: ["instagram", "twitter", "tiktok", "pinterest"],
+    priceThreshold: 25,  // Lower threshold, .com preferred
+    industryHint: "ecommerce" as const
+  },
+  creative: {
+    // Creative agencies: design, media, content
+    tlds: ["design", "studio", "io", "co", "com"],
+    suggestStyle: "creative" as const,
+    socialPlatforms: ["instagram", "twitter", "dribbble", "behance"],
+    priceThreshold: 35,
+    industryHint: "creative" as const
+  },
+  fintech: {
+    // Financial technology: payments, banking, crypto
+    tlds: ["com", "io", "finance", "money", "app"],
+    suggestStyle: "brandable" as const,
+    socialPlatforms: ["twitter", "linkedin", "github"],
+    priceThreshold: 100,  // Premium domains acceptable
+    industryHint: "finance" as const
+  },
+  healthcare: {
+    // Healthcare & wellness startups
+    tlds: ["health", "care", "com", "io", "app"],
+    suggestStyle: "descriptive" as const,
+    socialPlatforms: ["twitter", "linkedin", "facebook"],
+    priceThreshold: 40,
+    industryHint: "health" as const
+  }
+};
+
+type StartupType = keyof typeof STARTUP_TYPE_CONFIGS;
+```
+
+#### Complete Startup Research Pipeline with Error Recovery
+
+Production-ready pipeline with comprehensive error handling and retry logic:
+
+```typescript
+import {
+  searchDomain,
+  tldInfo,
+  suggestDomainsSmart,
+  checkSocials,
+  compareRegistrars
+} from 'domain-search-mcp';
+
+interface PipelineResult {
+  success: boolean;
+  startupName: string;
+  startupType: StartupType;
+  domains: DomainRecommendation[];
+  socialAnalysis: SocialAnalysis[];
+  tldContext: TldContext[];
+  errors: PipelineError[];
+  executionTime: number;
+}
+
+interface PipelineError {
+  stage: string;
+  error: string;
+  recoverable: boolean;
+  fallbackUsed?: string;
+}
+
+// Retry wrapper with exponential backoff
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: { maxRetries: number; baseDelay: number; stageName: string }
+): Promise<{ result: T | null; error: PipelineError | null }> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
+    try {
+      const result = await fn();
+      return { result, error: null };
+    } catch (err) {
+      lastError = err as Error;
+
+      if (attempt < options.maxRetries) {
+        const delay = options.baseDelay * Math.pow(2, attempt);
+        console.log(`⚠️ ${options.stageName} failed, retrying in ${delay}ms...`);
+        await new Promise(r => setTimeout(r, delay));
+      }
+    }
+  }
+
+  return {
+    result: null,
+    error: {
+      stage: options.stageName,
+      error: lastError?.message || 'Unknown error',
+      recoverable: false
+    }
+  };
+}
+
+async function startupDomainResearchPipeline(
+  startupName: string,
+  startupType: StartupType = 'tech'
+): Promise<PipelineResult> {
+  const startTime = Date.now();
+  const config = STARTUP_TYPE_CONFIGS[startupType];
+  const errors: PipelineError[] = [];
+
+  console.log(`\n🚀 Starting domain research for "${startupName}" (${startupType} startup)`);
+  console.log(`   Preferred TLDs: ${config.tlds.join(', ')}`);
+  console.log(`   Social platforms: ${config.socialPlatforms.join(', ')}`);
+
+  // Stage 1: Get TLD context with error recovery
+  console.log('\n📋 Stage 1: Fetching TLD information...');
+  const tldResults: TldContext[] = [];
+
+  for (const tld of config.tlds) {
+    const { result, error } = await withRetry(
+      () => tldInfo({ tld, detailed: true }),
+      { maxRetries: 2, baseDelay: 1000, stageName: `tld_info(${tld})` }
+    );
+
+    if (result) {
+      tldResults.push({
+        tld: result.tld,
+        description: result.description,
+        priceRange: result.price_range,
+        typicalUse: result.typical_use,
+        restrictions: result.restrictions,
+        recommendation: result.recommendation
+      });
+      console.log(`   ✅ .${tld}: ${result.description.substring(0, 50)}...`);
+    } else if (error) {
+      errors.push(error);
+      console.log(`   ⚠️ .${tld}: Failed to fetch info`);
+    }
+  }
+
+  // Stage 2: Generate smart suggestions with startup context
+  console.log('\n💡 Stage 2: Generating domain suggestions...');
+
+  const { result: suggestions, error: suggestError } = await withRetry(
+    () => suggestDomainsSmart({
+      query: startupName,
+      tld: config.tlds[0],  // Primary TLD
+      style: config.suggestStyle,
+      industry: config.industryHint,
+      max_suggestions: 20,
+      include_premium: config.priceThreshold > 50
+    }),
+    { maxRetries: 2, baseDelay: 1500, stageName: 'suggest_domains_smart' }
+  );
+
+  if (suggestError) {
+    errors.push(suggestError);
+    console.log('   ⚠️ Smart suggestions failed, falling back to basic search');
+  }
+
+  // Stage 3: Check availability across all preferred TLDs
+  console.log('\n🔍 Stage 3: Checking domain availability...');
+
+  const { result: availability, error: searchError } = await withRetry(
+    () => searchDomain({
+      domain_name: startupName,
+      tlds: config.tlds
+    }),
+    { maxRetries: 3, baseDelay: 1000, stageName: 'search_domain' }
+  );
+
+  if (searchError) {
+    errors.push(searchError);
+  }
+
+  // Stage 4: Social media availability with platform-specific handling
+  console.log('\n🌐 Stage 4: Checking social media availability...');
+
+  const { result: socialResults, error: socialError } = await withRetry(
+    () => checkSocials({
+      name: startupName.toLowerCase().replace(/[^a-z0-9]/g, ''),
+      platforms: config.socialPlatforms
+    }),
+    { maxRetries: 2, baseDelay: 2000, stageName: 'check_socials' }
+  );
+
+  // Process social results with confidence levels
+  const socialAnalysis: SocialAnalysis[] = [];
+  if (socialResults) {
+    for (const platform of socialResults.platforms) {
+      socialAnalysis.push({
+        platform: platform.platform,
+        available: platform.available,
+        confidence: platform.confidence || 'unknown',
+        url: platform.profile_url,
+        recommendation: getSocialRecommendation(platform, startupType)
+      });
+
+      const status = platform.available ? '✅' : '❌';
+      const conf = platform.confidence ? ` (${platform.confidence})` : '';
+      console.log(`   ${status} ${platform.platform}${conf}`);
+    }
+  } else if (socialError) {
+    errors.push({
+      ...socialError,
+      fallbackUsed: 'Manual verification recommended'
+    });
+  }
+
+  // Stage 5: Price comparison for available domains
+  console.log('\n💰 Stage 5: Comparing registrar pricing...');
+
+  const domains: DomainRecommendation[] = [];
+  const availableDomains = availability?.results.filter(r => r.available) || [];
+
+  for (const domain of availableDomains.slice(0, 5)) {
+    const domainName = domain.domain.split('.')[0];
+    const tld = domain.domain.split('.').pop()!;
+
+    const { result: pricing } = await withRetry(
+      () => compareRegistrars({ domain: domainName, tld }),
+      { maxRetries: 1, baseDelay: 1000, stageName: `compare_registrars(${domain.domain})` }
+    );
+
+    const tldContext = tldResults.find(t => t.tld === tld);
+
+    domains.push({
+      domain: domain.domain,
+      available: true,
+      priceFirstYear: pricing?.best_first_year?.price || domain.price_first_year,
+      priceRenewal: pricing?.best_renewal?.price,
+      bestRegistrar: pricing?.best_first_year?.registrar || domain.registrar,
+      tldInfo: tldContext,
+      withinBudget: (domain.price_first_year || 0) <= config.priceThreshold,
+      score: calculateDomainScore(domain, tldContext, socialAnalysis, config)
+    });
+
+    console.log(`   ${domain.domain}: $${domain.price_first_year}/yr`);
+  }
+
+  // Sort by score
+  domains.sort((a, b) => (b.score || 0) - (a.score || 0));
+
+  const executionTime = Date.now() - startTime;
+
+  console.log(`\n✨ Research complete in ${executionTime}ms`);
+  console.log(`   ${domains.length} available domains found`);
+  console.log(`   ${errors.length} errors encountered`);
+
+  return {
+    success: errors.length === 0,
+    startupName,
+    startupType,
+    domains,
+    socialAnalysis,
+    tldContext: tldResults,
+    errors,
+    executionTime
+  };
+}
+
+// Helper: Calculate domain score based on multiple factors
+function calculateDomainScore(
+  domain: any,
+  tldContext: TldContext | undefined,
+  social: SocialAnalysis[],
+  config: typeof STARTUP_TYPE_CONFIGS[StartupType]
+): number {
+  let score = 50;  // Base score
+
+  // Price factor (lower is better, up to threshold)
+  const price = domain.price_first_year || 0;
+  if (price <= config.priceThreshold * 0.5) score += 20;
+  else if (price <= config.priceThreshold) score += 10;
+  else score -= 10;
+
+  // TLD preference factor
+  const tldIndex = config.tlds.indexOf(domain.domain.split('.').pop());
+  if (tldIndex === 0) score += 15;  // Primary TLD
+  else if (tldIndex <= 2) score += 10;
+  else if (tldIndex > -1) score += 5;
+
+  // Social availability factor
+  const availableSocials = social.filter(s => s.available).length;
+  score += availableSocials * 5;
+
+  // Length factor (shorter is better)
+  const nameLength = domain.domain.split('.')[0].length;
+  if (nameLength <= 6) score += 10;
+  else if (nameLength <= 10) score += 5;
+  else if (nameLength > 15) score -= 5;
+
+  return Math.max(0, Math.min(100, score));
+}
+
+// Helper: Get platform-specific recommendations
+function getSocialRecommendation(
+  platform: any,
+  startupType: StartupType
+): string {
+  if (platform.available) {
+    return `Register @${platform.name} immediately to secure brand consistency`;
+  }
+
+  const alternatives: Record<string, string> = {
+    twitter: 'Consider @get[name], @[name]app, or @[name]hq',
+    github: 'Use organization account or add suffix like -app, -io',
+    instagram: 'Try [name].official, get[name], or [name]_app',
+    npm: 'Use scoped package @[org]/[name]',
+    linkedin: 'Create company page with full business name'
+  };
+
+  return alternatives[platform.platform] || 'Consider alternative naming';
+}
+
+// Usage with different startup types
+const techStartupReport = await startupDomainResearchPipeline("codeflow", "tech");
+const ecommerceReport = await startupDomainResearchPipeline("shopwave", "ecommerce");
+const creativeReport = await startupDomainResearchPipeline("pixelcraft", "creative");
+```
+
+#### Formatted Report Output by Startup Type
+
+Generate customized reports based on startup category:
+
+```typescript
+function formatStartupReport(result: PipelineResult): string {
+  const { startupName, startupType, domains, socialAnalysis, tldContext, errors } = result;
+
+  let report = `
+╔══════════════════════════════════════════════════════════════╗
+║  DOMAIN RESEARCH REPORT: ${startupName.toUpperCase().padEnd(35)}║
+║  Type: ${startupType.toUpperCase()} STARTUP${' '.repeat(45 - startupType.length)}║
+║  Generated: ${new Date().toISOString().split('T')[0]}${' '.repeat(40)}║
+╚══════════════════════════════════════════════════════════════╝
+`;
+
+  // TLD Analysis Section
+  report += `\n┌─ TLD ANALYSIS ${'─'.repeat(46)}┐\n`;
+  for (const tld of tldContext) {
+    report += `│ .${tld.tld.padEnd(6)} │ ${tld.description.substring(0, 40).padEnd(40)} │\n`;
+    report += `│        │ Price: $${tld.priceRange.min}-$${tld.priceRange.max}/yr`.padEnd(52) + `│\n`;
+  }
+  report += `└${'─'.repeat(60)}┘\n`;
+
+  // Domain Recommendations Section
+  report += `\n┌─ TOP DOMAIN RECOMMENDATIONS ${'─'.repeat(31)}┐\n`;
+  report += `│ Rank │ Domain${' '.repeat(20)}│ Price  │ Score │\n`;
+  report += `├──────┼${'-'.repeat(26)}┼────────┼───────┤\n`;
+
+  domains.slice(0, 5).forEach((d, i) => {
+    const rank = `#${i + 1}`.padEnd(4);
+    const domain = d.domain.padEnd(25);
+    const price = `$${d.priceFirstYear}`.padEnd(6);
+    const score = `${d.score}/100`;
+    report += `│ ${rank} │ ${domain} │ ${price} │ ${score.padEnd(5)} │\n`;
+  });
+  report += `└${'─'.repeat(60)}┘\n`;
+
+  // Social Media Section
+  report += `\n┌─ SOCIAL MEDIA AVAILABILITY ${'─'.repeat(32)}┐\n`;
+  for (const social of socialAnalysis) {
+    const status = social.available ? '✅ Available' : '❌ Taken';
+    const conf = social.confidence !== 'unknown' ? ` (${social.confidence})` : '';
+    report += `│ ${social.platform.padEnd(12)} │ ${status}${conf}`.padEnd(48) + `│\n`;
+    if (!social.available) {
+      report += `│              │ → ${social.recommendation.substring(0, 35)}`.padEnd(48) + `│\n`;
+    }
+  }
+  report += `└${'─'.repeat(60)}┘\n`;
+
+  // Recommendations by startup type
+  report += `\n┌─ ${startupType.toUpperCase()} STARTUP RECOMMENDATIONS ${'─'.repeat(26)}┐\n`;
+
+  const typeRecommendations: Record<StartupType, string[]> = {
+    tech: [
+      '→ Prioritize .io or .dev for developer credibility',
+      '→ Secure GitHub org and npm package name',
+      '→ Consider .sh for CLI tools'
+    ],
+    ecommerce: [
+      '→ .com is essential for consumer trust',
+      '→ Secure Instagram and TikTok handles',
+      '→ Consider .shop or .store as secondary'
+    ],
+    creative: [
+      '→ .design or .studio signals creative focus',
+      '→ Instagram presence is critical',
+      '→ Shorter names work better for branding'
+    ],
+    fintech: [
+      '→ .com required for financial credibility',
+      '→ Avoid hyphens - trust signals matter',
+      '→ LinkedIn company page essential'
+    ],
+    healthcare: [
+      '→ .health TLD builds trust',
+      '→ Avoid playful names - professionalism matters',
+      '→ Verify regulatory compliance for domain use'
+    ]
+  };
+
+  for (const rec of typeRecommendations[startupType]) {
+    report += `│ ${rec.padEnd(58)} │\n`;
+  }
+  report += `└${'─'.repeat(60)}┘\n`;
+
+  // Error summary if any
+  if (errors.length > 0) {
+    report += `\n⚠️ WARNINGS: ${errors.length} issues encountered during research\n`;
+    errors.forEach(e => {
+      report += `   • ${e.stage}: ${e.error}\n`;
+    });
+  }
+
+  return report;
+}
+
+// Generate and print formatted report
+const result = await startupDomainResearchPipeline("nexaflow", "tech");
+console.log(formatStartupReport(result));
+```
+
+**Sample Output:**
+```
+╔══════════════════════════════════════════════════════════════╗
+║  DOMAIN RESEARCH REPORT: NEXAFLOW                            ║
+║  Type: TECH STARTUP                                          ║
+║  Generated: 2024-01-15                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+┌─ TLD ANALYSIS ──────────────────────────────────────────────┐
+│ .io     │ Popular with tech startups and SaaS              │
+│         │ Price: $32-$44/yr                                 │
+│ .dev    │ Google TLD for developers                        │
+│         │ Price: $12-$16/yr                                 │
+│ .app    │ Mobile and web applications                      │
+│         │ Price: $14-$18/yr                                 │
+└──────────────────────────────────────────────────────────────┘
+
+┌─ TOP DOMAIN RECOMMENDATIONS ─────────────────────────────────┐
+│ Rank │ Domain                    │ Price  │ Score │
+├──────┼──────────────────────────┼────────┼───────┤
+│ #1   │ nexaflow.dev              │ $14.95 │ 85/100│
+│ #2   │ nexaflow.io               │ $39.95 │ 78/100│
+│ #3   │ nexaflow.app              │ $14.95 │ 75/100│
+│ #4   │ nexaflow.com              │ $9.95  │ 72/100│
+│ #5   │ nexaflow.sh               │ $24.95 │ 65/100│
+└──────────────────────────────────────────────────────────────┘
+
+┌─ SOCIAL MEDIA AVAILABILITY ──────────────────────────────────┐
+│ github       │ ✅ Available (high)                          │
+│ twitter      │ ❌ Taken (high)                              │
+│              │ → Consider @getnexaflow, @nexaflowapp        │
+│ npm          │ ✅ Available (high)                          │
+│ pypi         │ ✅ Available (high)                          │
+│ producthunt  │ ✅ Available (medium)                        │
+└──────────────────────────────────────────────────────────────┘
+
+┌─ TECH STARTUP RECOMMENDATIONS ───────────────────────────────┐
+│ → Prioritize .io or .dev for developer credibility           │
+│ → Secure GitHub org and npm package name                     │
+│ → Consider .sh for CLI tools                                 │
+└──────────────────────────────────────────────────────────────┘
+```
+
+#### Advanced Error Recovery: Circuit Breaker Pattern
+
+For production startup research pipelines, implement a circuit breaker to handle API failures gracefully:
+
+```typescript
+/**
+ * Circuit Breaker for Domain Research Pipeline
+ *
+ * States:
+ * - CLOSED: Normal operation, requests flow through
+ * - OPEN: Too many failures, requests fail fast
+ * - HALF_OPEN: Testing if service recovered
+ */
+class CircuitBreaker {
+  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';
+  private failureCount = 0;
+  private successCount = 0;
+  private lastFailureTime = 0;
+
+  constructor(
+    private readonly options: {
+      failureThreshold: number;      // Failures before opening circuit
+      successThreshold: number;      // Successes to close circuit
+      timeout: number;               // Time before trying half-open (ms)
+      fallback?: () => Promise<any>; // Fallback function when open
+    }
+  ) {}
+
+  async execute<T>(operation: () => Promise<T>, operationName: string): Promise<T> {
+    // Check if circuit should transition from OPEN to HALF_OPEN
+    if (this.state === 'OPEN') {
+      if (Date.now() - this.lastFailureTime >= this.options.timeout) {
+        this.state = 'HALF_OPEN';
+        console.log(`⚡ Circuit ${operationName}: OPEN → HALF_OPEN (testing recovery)`);
+      } else {
+        // Circuit is open, fail fast or use fallback
+        if (this.options.fallback) {
+          console.log(`⚡ Circuit ${operationName}: OPEN (using fallback)`);
+          return this.options.fallback();
+        }
+        throw new Error(`Circuit breaker is OPEN for ${operationName}`);
+      }
+    }
+
+    try {
+      const result = await operation();
+      this.onSuccess(operationName);
+      return result;
+    } catch (error) {
+      this.onFailure(operationName);
+      throw error;
+    }
+  }
+
+  private onSuccess(operationName: string) {
+    if (this.state === 'HALF_OPEN') {
+      this.successCount++;
+      if (this.successCount >= this.options.successThreshold) {
+        this.state = 'CLOSED';
+        this.failureCount = 0;
+        this.successCount = 0;
+        console.log(`✅ Circuit ${operationName}: HALF_OPEN → CLOSED (recovered)`);
+      }
+    } else {
+      this.failureCount = 0; // Reset on success in CLOSED state
+    }
+  }
+
+  private onFailure(operationName: string) {
+    this.failureCount++;
+    this.lastFailureTime = Date.now();
+
+    if (this.state === 'HALF_OPEN') {
+      this.state = 'OPEN';
+      this.successCount = 0;
+      console.log(`❌ Circuit ${operationName}: HALF_OPEN → OPEN (still failing)`);
+    } else if (this.failureCount >= this.options.failureThreshold) {
+      this.state = 'OPEN';
+      console.log(`❌ Circuit ${operationName}: CLOSED → OPEN (threshold reached)`);
+    }
+  }
+
+  getState() {
+    return { state: this.state, failures: this.failureCount, successes: this.successCount };
+  }
+}
+
+// Create circuit breakers for each tool in the pipeline
+const circuitBreakers = {
+  search_domain: new CircuitBreaker({
+    failureThreshold: 3,
+    successThreshold: 2,
+    timeout: 30000,
+    fallback: async () => ({ results: [], fromFallback: true })
+  }),
+  tld_info: new CircuitBreaker({
+    failureThreshold: 5,
+    successThreshold: 1,
+    timeout: 60000,
+    fallback: async () => ({ tld: "unknown", description: "Info unavailable" })
+  }),
+  suggest_domains: new CircuitBreaker({
+    failureThreshold: 3,
+    successThreshold: 2,
+    timeout: 30000
+  }),
+  check_socials: new CircuitBreaker({
+    failureThreshold: 5,
+    successThreshold: 1,
+    timeout: 60000,
+    fallback: async () => ({ platforms: [], error: "Social check unavailable" })
+  })
+};
+
+// Usage in startup research pipeline
+async function resilientStartupResearch(startupName: string, startupType: StartupType) {
+  const config = STARTUP_TYPE_CONFIGS[startupType];
+  const results = {
+    tldAnalysis: [] as any[],
+    domains: [] as any[],
+    socials: null as any,
+    errors: [] as string[]
+  };
+
+  // Step 1: TLD Analysis with circuit breaker
+  for (const tld of config.tlds) {
+    try {
+      const info = await circuitBreakers.tld_info.execute(
+        () => tldInfo({ tld, detailed: true }),
+        `tld_info(${tld})`
+      );
+      results.tldAnalysis.push(info);
+    } catch (error) {
+      results.errors.push(`tld_info(${tld}): ${error.message}`);
+    }
+  }
+
+  // Step 2: Domain search with circuit breaker
+  try {
+    const searchResult = await circuitBreakers.search_domain.execute(
+      () => searchDomain({ domain_name: startupName, tlds: config.tlds }),
+      'search_domain'
+    );
+    results.domains = searchResult.results;
+  } catch (error) {
+    results.errors.push(`search_domain: ${error.message}`);
+  }
+
+  // Step 3: Social check with circuit breaker
+  try {
+    results.socials = await circuitBreakers.check_socials.execute(
+      () => checkSocials({ name: startupName, platforms: config.socialPlatforms }),
+      'check_socials'
+    );
+  } catch (error) {
+    results.errors.push(`check_socials: ${error.message}`);
+  }
+
+  // Log circuit breaker states for monitoring
+  console.log('Circuit Breaker States:', {
+    search_domain: circuitBreakers.search_domain.getState(),
+    tld_info: circuitBreakers.tld_info.getState(),
+    check_socials: circuitBreakers.check_socials.getState()
+  });
+
+  return results;
+}
+
+// Example usage with automatic recovery
+const result = await resilientStartupResearch("nexaflow", "tech");
+// If APIs fail repeatedly, circuit opens and uses fallbacks
+// After timeout, circuit tests recovery with half-open state
+```
+
 ## Security
 
 - API keys are never logged (automatic secret masking)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domain-search-mcp",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "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",