domain-search-mcp 1.2.8 → 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,109 @@ 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:
@@ -4903,6 +5385,180 @@ console.log(formatStartupReport(result));
 └──────────────────────────────────────────────────────────────┘
 ```
 
+#### 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.8",
+  "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",