domain-search-mcp 1.2.4 → 1.2.6

package/README.md

@@ -247,6 +247,78 @@ for (const domain of result.results) {
 
 Check up to 100 domains at once with built-in rate limiting and progress tracking.
 
+---
+
+#### Quick Start: Initialize and Run bulk_search
+
+```typescript
+// Initialize bulk_search for checking 50 domains
+import { bulkSearch } from 'domain-search-mcp';
+
+// Step 1: Prepare your domain list (max 100)
+const domainsToCheck = [
+  "techflow", "datawise", "cloudpeak", "aiforge", "bytecraft",
+  "codestream", "devpulse", "syncwave", "logiclab", "pixelcraft"
+  // ... up to 100 domains
+];
+
+// Step 2: Initialize and call bulk_search
+async function initBulkSearch(domains: string[], tld: string = "com") {
+  console.log(`Initializing bulk_search for ${domains.length} domains...`);
+
+  const result = await bulkSearch({
+    domains: domains,       // Array of domain names (without TLD)
+    tld: tld,               // Single TLD to check (e.g., "com", "io")
+    concurrency: 10         // Optional: parallel requests (1-20)
+  });
+
+  // Process results
+  console.log(`✅ Checked ${result.summary.total} domains in ${result.summary.duration_ms}ms`);
+  console.log(`   Available: ${result.summary.available}`);
+  console.log(`   Taken: ${result.summary.taken}`);
+  console.log(`   Errors: ${result.summary.errors}`);
+
+  return result;
+}
+
+// Step 3: Run the bulk search
+const results = await initBulkSearch(domainsToCheck, "io");
+
+// Access available domains
+const availableDomains = results.results.filter(r => r.available);
+availableDomains.forEach(d => {
+  console.log(`${d.domain} - $${d.price_first_year}/yr`);
+});
+```
+
+**JavaScript Quick Start:**
+
+```javascript
+// Initialize bulk_search with fetch API
+async function initBulkSearch(domains, tld = 'com') {
+  const response = await fetch('http://localhost:3000/bulk_search', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      domains: domains,
+      tld: tld,
+      concurrency: 10
+    })
+  });
+
+  const result = await response.json();
+  console.log(`Checked ${result.summary.total} domains`);
+  console.log(`Available: ${result.summary.available}`);
+  return result;
+}
+
+// Usage
+const domains = ['startup1', 'startup2', 'startup3'];
+const result = await initBulkSearch(domains, 'io');
+```
+
+---
+
 **API Endpoint:** `POST /bulk_search`
 
 **Request Parameters:**
@@ -501,6 +573,132 @@ interface CompareRegistrarsResponse {
 }
 ```
 
+#### Example: Finding the Cheapest Registrar for 'startup.io'
+
+This is the complete workflow for finding and presenting the cheapest registrar for registering `startup.io`:
+
+```typescript
+// Find the cheapest registrar for startup.io and present pricing comparison
+
+async function findCheapestRegistrarForStartupIO() {
+  // Step 1: Compare prices across all available registrars
+  const comparison = await compareRegistrars({
+    domain: "startup",
+    tld: "io",
+    registrars: ["porkbun", "namecheap"]
+  });
+
+  // Step 2: Check if domain is available
+  if (!comparison.available) {
+    console.log("startup.io is not available for registration");
+    return null;
+  }
+
+  // Step 3: Extract pricing information
+  const prices = comparison.registrar_prices;
+  console.log("\n📊 PRICING COMPARISON FOR startup.io\n");
+  console.log("─".repeat(50));
+  console.log("REGISTRAR       FIRST YEAR    RENEWAL       PRIVACY");
+  console.log("─".repeat(50));
+
+  for (const [registrar, pricing] of Object.entries(prices)) {
+    if (pricing.error) {
+      console.log(`${registrar.padEnd(15)} Error: ${pricing.error}`);
+    } else {
+      const firstYear = `$${pricing.first_year}`.padEnd(13);
+      const renewal = `$${pricing.renewal}`.padEnd(13);
+      const privacy = pricing.privacy_included ? "✅ Included" : "❌ Extra";
+      console.log(`${registrar.padEnd(15)} ${firstYear} ${renewal} ${privacy}`);
+    }
+  }
+
+  console.log("─".repeat(50));
+
+  // Step 4: Present the cheapest option
+  const cheapest = comparison.best_first_year;
+  const bestRenewal = comparison.best_renewal;
+
+  console.log(`\n✨ CHEAPEST FIRST YEAR: ${cheapest.registrar} at $${cheapest.price}`);
+  console.log(`🔄 BEST RENEWAL RATE:   ${bestRenewal.registrar} at $${bestRenewal.price}`);
+  console.log(`\n💰 5-YEAR SAVINGS:      $${comparison.savings.over_5_years}`);
+  console.log(`\n💡 ${comparison.recommendation}`);
+
+  return {
+    cheapestRegistrar: cheapest.registrar,
+    firstYearPrice: cheapest.price,
+    renewalPrice: prices[cheapest.registrar].renewal,
+    recommendation: comparison.recommendation,
+    allPrices: prices
+  };
+}
+
+// Usage
+const result = await findCheapestRegistrarForStartupIO();
+
+// Output:
+// 📊 PRICING COMPARISON FOR startup.io
+//
+// ──────────────────────────────────────────────────
+// REGISTRAR       FIRST YEAR    RENEWAL       PRIVACY
+// ──────────────────────────────────────────────────
+// porkbun         $29.88        $29.88        ✅ Included
+// namecheap       $32.98        $32.98        ✅ Included
+// ──────────────────────────────────────────────────
+//
+// ✨ CHEAPEST FIRST YEAR: porkbun at $29.88
+// 🔄 BEST RENEWAL RATE:   porkbun at $29.88
+//
+// 💰 5-YEAR SAVINGS:      $15.50
+//
+// 💡 Porkbun offers the best price for both first year and renewal
+```
+
+**JavaScript Example for startup.io:**
+
+```javascript
+// Using fetch API to compare registrars for startup.io
+async function compareStartupIO() {
+  const response = await fetch('http://localhost:3000/compare_registrars', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      domain: 'startup',
+      tld: 'io'
+    })
+  });
+
+  const data = await response.json();
+
+  if (!data.available) {
+    console.log('startup.io is taken');
+    return;
+  }
+
+  // Display comparison to user
+  console.log(`\nPricing for startup.io:\n`);
+
+  Object.entries(data.registrar_prices).forEach(([registrar, prices]) => {
+    console.log(`${registrar}: $${prices.first_year}/yr (renewal: $${prices.renewal}/yr)`);
+  });
+
+  console.log(`\n✅ Best price: ${data.best_first_year.registrar} at $${data.best_first_year.price}/yr`);
+  console.log(`💡 ${data.recommendation}`);
+
+  return data;
+}
+
+// Run comparison
+const comparison = await compareStartupIO();
+// Output:
+// Pricing for startup.io:
+//
+// porkbun: $29.88/yr (renewal: $29.88/yr)
+// namecheap: $32.98/yr (renewal: $32.98/yr)
+//
+// ✅ Best price: porkbun at $29.88/yr
+// 💡 Porkbun offers the best price for both first year and renewal
+```
+
 **Handling Edge Cases:**
 
 ```typescript
@@ -1201,7 +1399,152 @@ console.log(`Price range: $${tldData.price_range.min} - $${tldData.price_range.m
 
 ### check_socials
 
-Verify username availability across 10 platforms:
+Verify username availability across 10 platforms simultaneously.
+
+**API Endpoint:** `POST /check_socials`
+
+**Request Parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `name` | string | Yes | - | Username to check |
+| `platforms` | string[] | No | ["github", "twitter", "reddit", "npm"] | Platforms to check |
+
+**Supported Platforms:**
+
+| Platform | ID | Confidence | Detection Method |
+|----------|-----|------------|------------------|
+| GitHub | `github` | High | Public API |
+| Twitter/X | `twitter` | High | oembed API |
+| npm | `npm` | High | Registry API |
+| PyPI | `pypi` | High | Package API |
+| Reddit | `reddit` | High | Profile check |
+| YouTube | `youtube` | Medium | Channel page |
+| ProductHunt | `producthunt` | Medium | Profile page |
+| Instagram | `instagram` | Low | Blocks automation |
+| LinkedIn | `linkedin` | Low | Blocks automation |
+| TikTok | `tiktok` | Low | Blocks automation |
+
+**Response Type:**
+
+```typescript
+interface CheckSocialsResponse {
+  name: string;                    // Username checked
+  results: Array<{
+    platform: string;              // Platform ID (github, twitter, etc.)
+    available: boolean;            // Whether username is available
+    confidence: "high" | "medium" | "low";
+    url: string;                   // Direct URL to profile/claim page
+    error?: string;                // Error message if check failed
+    errorCode?: string;            // RATE_LIMIT, TIMEOUT, BLOCKED, etc.
+    responseTime?: number;         // Check duration in ms
+  }>;
+  insights: string[];              // Human-readable summary
+  summary: {
+    available: number;             // Count of available platforms
+    taken: number;                 // Count of taken platforms
+    unknown: number;               // Count of low-confidence/error platforms
+  };
+}
+```
+
+---
+
+#### Quick Start: Check GitHub, Twitter, and Instagram
+
+This is the most common use case - verify username on the three main platforms:
+
+```typescript
+// Quick Start: Check 'myproject' on GitHub, Twitter, and Instagram simultaneously
+
+import { checkSocials } from 'domain-search-mcp';
+
+async function checkUsernameOnMainPlatforms(username: string) {
+  // Call check_socials with the three platforms
+  const result = await checkSocials({
+    name: username,
+    platforms: ["github", "twitter", "instagram"]
+  });
+
+  // Process results
+  console.log(`\nChecking "${username}" on GitHub, Twitter, Instagram:\n`);
+
+  for (const platform of result.results) {
+    const status = platform.available ? "✅ Available" : "❌ Taken";
+    const confidence = platform.confidence === "low" ? " (verify manually)" : "";
+    console.log(`  ${platform.platform.padEnd(12)} ${status}${confidence}`);
+    console.log(`  └─ ${platform.url}`);
+  }
+
+  // Summary
+  const available = result.results.filter(r => r.available && r.confidence !== "low");
+  const taken = result.results.filter(r => !r.available);
+  const manual = result.results.filter(r => r.confidence === "low");
+
+  console.log(`\nSummary: ${available.length} available, ${taken.length} taken, ${manual.length} need manual check`);
+
+  return {
+    available: available.map(r => ({ platform: r.platform, url: r.url })),
+    taken: taken.map(r => r.platform),
+    verifyManually: manual.map(r => ({ platform: r.platform, url: r.url }))
+  };
+}
+
+// Usage
+const result = await checkUsernameOnMainPlatforms("myproject");
+
+// Output:
+// Checking "myproject" on GitHub, Twitter, Instagram:
+//
+//   github       ✅ Available
+//   └─ https://github.com/myproject
+//   twitter      ❌ Taken
+//   └─ https://twitter.com/myproject
+//   instagram    ✅ Available (verify manually)
+//   └─ https://instagram.com/myproject
+//
+// Summary: 1 available, 1 taken, 1 need manual check
+```
+
+**JavaScript Quick Start:**
+
+```javascript
+// Check GitHub, Twitter, Instagram for a project name
+async function checkProjectSocials(projectName) {
+  const response = await fetch('http://localhost:3000/check_socials', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      name: projectName,
+      platforms: ['github', 'twitter', 'instagram']
+    })
+  });
+
+  const data = await response.json();
+
+  // Display results
+  console.log(`Social media check for "${projectName}":`);
+  data.results.forEach(r => {
+    const icon = r.available ? '✅' : '❌';
+    const note = r.confidence === 'low' ? ' (verify manually)' : '';
+    console.log(`  ${icon} ${r.platform}: ${r.available ? 'Available' : 'Taken'}${note}`);
+  });
+
+  return data;
+}
+
+// Example
+const socials = await checkProjectSocials('myproject');
+// Output:
+// Social media check for "myproject":
+//   ✅ github: Available
+//   ❌ twitter: Taken
+//   ✅ instagram: Available (verify manually)
+```
+
+---
+
+**Basic Example:**
 
 ```typescript
 // Input
@@ -1214,15 +1557,31 @@ Verify username availability across 10 platforms:
 {
   "name": "vibecoding",
   "results": [
-    { "platform": "github", "available": true, "confidence": "high" },
-    { "platform": "twitter", "available": false, "confidence": "high" },
-    { "platform": "instagram", "available": true, "confidence": "low" }
+    {
+      "platform": "github",
+      "available": true,
+      "confidence": "high",
+      "url": "https://github.com/vibecoding"
+    },
+    {
+      "platform": "twitter",
+      "available": false,
+      "confidence": "high",
+      "url": "https://twitter.com/vibecoding"
+    },
+    {
+      "platform": "instagram",
+      "available": true,
+      "confidence": "low",
+      "url": "https://instagram.com/vibecoding"
+    }
   ],
   "insights": [
     "✅ vibecoding is available on: github",
     "❌ vibecoding is taken on: twitter",
     "⚠️ Could not reliably check: instagram (check manually)"
-  ]
+  ],
+  "summary": { "available": 2, "taken": 1, "unknown": 0 }
 }
 ```
 
@@ -1437,16 +1796,57 @@ With Porkbun API:
 
 #### Initializing Domain Search MCP with API Keys
 
-**Step 1: Get API Keys**
+**Step 1: Get Porkbun API Keys (Free, Recommended)**
 
-```bash
-# Porkbun (Recommended - Free, Fast, Reliable)
-# Visit: https://porkbun.com/account/api
-# Click "Create API Key" → Copy both API Key and Secret Key
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  HOW TO GET PORKBUN API KEYS (5 minutes)                        │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Go to: https://porkbun.com/account/api                      │
+│                                                                 │
+│  2. Log in or create a free account                             │
+│     - No credit card required                                   │
+│     - Email verification needed                                 │
+│                                                                 │
+│  3. Click "Create API Key"                                      │
+│                                                                 │
+│  4. You'll receive TWO keys:                                    │
+│     ┌────────────────────────────────────────────────────────┐  │
+│     │ API Key:    pk1_abc123def456ghi789jkl012mno345...      │  │
+│     │ Secret Key: sk1_xyz789abc123def456ghi789jkl012...      │  │
+│     └────────────────────────────────────────────────────────┘  │
+│     ⚠️ SAVE BOTH - Secret Key is shown only once!               │
+│                                                                 │
+│  5. Done! No IP whitelist or domain ownership required          │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Step 1b: Get Namecheap API Keys (Optional)**
 
-# Namecheap (Optional - Requires IP Whitelist)
-# Visit: https://ap.www.namecheap.com/settings/tools/apiaccess
-# Enable API → Add your IP to whitelist → Copy credentials
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  HOW TO GET NAMECHEAP API KEYS                                  │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Prerequisites:                                                 │
+│  - Active Namecheap account with at least 1 domain OR           │
+│  - $50+ account balance                                         │
+│                                                                 │
+│  1. Go to: https://ap.www.namecheap.com/settings/tools/apiaccess│
+│                                                                 │
+│  2. Enable API Access (toggle ON)                               │
+│                                                                 │
+│  3. Whitelist your IP address:                                  │
+│     - Find your IP: curl ifconfig.me                            │
+│     - Add it to the whitelist                                   │
+│                                                                 │
+│  4. Copy your API Key and Username                              │
+│                                                                 │
+│  ⚠️ Note: Namecheap requires IP whitelisting for security       │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
 ```
 
 **Step 2: Create .env File**
@@ -1460,16 +1860,54 @@ cp .env.example .env
 # .env file contents
 # ==================
 
-# Porkbun API (Recommended - Free)
-PORKBUN_API_KEY=pk1_abc123def456...
-PORKBUN_SECRET_KEY=sk1_xyz789ghi012...
+# Porkbun API (Recommended - Free, no restrictions)
+PORKBUN_API_KEY=pk1_abc123def456ghi789jkl012mno345pqr678stu901vwx234
+PORKBUN_SECRET_KEY=sk1_xyz789abc123def456ghi789jkl012mno345pqr678stu901
 
-# Namecheap API (Optional)
+# Namecheap API (Optional - requires IP whitelist)
 NAMECHEAP_API_KEY=your_api_key_here
 NAMECHEAP_API_USER=your_username_here
 NAMECHEAP_CLIENT_IP=auto  # Optional, auto-detected if omitted
 ```
 
+**Why Porkbun is Recommended:**
+
+| Feature | Porkbun | Namecheap |
+|---------|---------|-----------|
+| **Cost** | Free | Free |
+| **Setup Time** | 2 minutes | 10+ minutes |
+| **IP Whitelist** | Not required | Required |
+| **Domain Ownership** | Not required | Required ($50 balance alternative) |
+| **Rate Limit** | 1000+ req/min | 500+ req/min |
+| **Response Time** | ~100ms | ~150ms |
+
+**Performance Benefits of API Keys (Detailed):**
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│  PERFORMANCE COMPARISON: 100 Domain Batch Search                   │
+├────────────────────────────────────────────────────────────────────┤
+│                                                                    │
+│  WITHOUT API KEYS (RDAP/WHOIS fallback):                           │
+│  ├─ Total time: 3-5 minutes                                        │
+│  ├─ Rate limit errors: 5-15 retries needed                         │
+│  ├─ Pricing data: ❌ Not available                                 │
+│  ├─ WHOIS privacy info: ❌ Not available                           │
+│  └─ Success rate: ~85% (some TLDs fail)                            │
+│                                                                    │
+│  WITH PORKBUN API:                                                 │
+│  ├─ Total time: 8-15 seconds (14x faster)                          │
+│  ├─ Rate limit errors: 0                                           │
+│  ├─ Pricing data: ✅ First year + renewal prices                   │
+│  ├─ WHOIS privacy info: ✅ Included                                │
+│  └─ Success rate: 99.9%                                            │
+│                                                                    │
+│  Time saved per 100 domains: ~4 minutes                            │
+│  Time saved per 1000 domains: ~40 minutes                          │
+│                                                                    │
+└────────────────────────────────────────────────────────────────────┘
+```
+
 **Step 3: Verify Configuration**
 
 ```typescript
@@ -1881,6 +2319,215 @@ Add to `.cursor/mcp.json`:
 
 Add to your Cline settings to enable MCP servers.
 
+### MCP Tool Invocation Patterns
+
+When using Domain Search MCP through an MCP-compatible client (Claude Desktop, Cursor, etc.), tools are invoked using the standard MCP tool call pattern:
+
+#### Basic MCP Tool Call Structure
+
+```typescript
+// MCP tool invocation pattern (as handled by the MCP client)
+// The client sends a tool_call request to the MCP server:
+
+// Tool: search_domain
+{
+  "tool": "search_domain",
+  "arguments": {
+    "domain_name": "vibecoding",
+    "tlds": ["com", "io", "dev"]
+  }
+}
+
+// Tool: check_socials
+{
+  "tool": "check_socials",
+  "arguments": {
+    "name": "myproject",
+    "platforms": ["github", "twitter", "instagram"]
+  }
+}
+
+// Tool: suggest_domains
+{
+  "tool": "suggest_domains",
+  "arguments": {
+    "base_name": "techapp",
+    "tld": "com",
+    "max_suggestions": 10,
+    "variants": ["prefixes", "suffixes", "hyphen"]
+  }
+}
+```
+
+#### MCP Tool Invocation via Claude Desktop
+
+When using Claude Desktop, simply describe what you want in natural language:
+
+```
+User: "Check if 'myproject' is available as a domain and on GitHub"
+
+Claude invokes MCP tools:
+1. search_domain({ domain_name: "myproject", tlds: ["com", "io", "dev"] })
+2. check_socials({ name: "myproject", platforms: ["github"] })
+
+Response: Shows domain availability with pricing and GitHub username status
+```
+
+#### Quick Reference: All MCP Tool Names
+
+| MCP Tool Name | Purpose | Primary Arguments |
+|---------------|---------|-------------------|
+| `search_domain` | Check availability + pricing | `domain_name`, `tlds[]` |
+| `bulk_search` | Check up to 100 domains | `domains[]`, `tld` |
+| `compare_registrars` | Compare prices | `domain`, `tld` |
+| `suggest_domains` | Get variations when taken | `base_name`, `tld`, `variants[]` |
+| `suggest_domains_smart` | AI-powered suggestions | `query`, `tld`, `style` |
+| `tld_info` | TLD details + restrictions | `tld`, `detailed` |
+| `check_socials` | Social username check | `name`, `platforms[]` |
+
+#### Programmatic MCP Tool Invocation (via MCP SDK)
+
+```typescript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+
+// Initialize MCP client
+const client = new Client({
+  name: "domain-search-client",
+  version: "1.0.0"
+});
+
+// Connect to the domain-search-mcp server
+await client.connect(transport);
+
+// Invoke MCP tools programmatically
+const domainResult = await client.callTool({
+  name: "search_domain",
+  arguments: {
+    domain_name: "myproject",
+    tlds: ["com", "io"]
+  }
+});
+
+const socialResult = await client.callTool({
+  name: "check_socials",
+  arguments: {
+    name: "myproject",
+    platforms: ["github", "twitter", "instagram"]
+  }
+});
+
+console.log("Domain results:", domainResult);
+console.log("Social results:", socialResult);
+```
+
+### Running as Local HTTP Server
+
+Domain Search MCP can also run as a standalone HTTP server for direct API access:
+
+#### Quick Start: Local Server Setup
+
+```bash
+# Step 1: Clone and install
+git clone https://github.com/dorukardahan/domain-search-mcp.git
+cd domain-search-mcp
+npm install
+
+# Step 2: Build the server
+npm run build
+
+# Step 3: Start the HTTP server
+npm start
+
+# Server runs at http://localhost:3000
+```
+
+#### Local Server Configuration
+
+```bash
+# Optional: Configure environment before starting
+cp .env.example .env
+
+# Edit .env to add API keys (optional but recommended)
+# PORKBUN_API_KEY=pk1_...
+# PORKBUN_SECRET_KEY=sk1_...
+
+# Set custom port (default: 3000)
+export PORT=3001
+
+# Start server
+npm start
+```
+
+#### Making API Requests to Local Server
+
+Once the server is running, you can make HTTP requests:
+
+```bash
+# Check domain availability
+curl -X POST http://localhost:3000/search_domain \
+  -H "Content-Type: application/json" \
+  -d '{"domain_name": "myproject", "tlds": ["com", "io"]}'
+
+# Check social media usernames
+curl -X POST http://localhost:3000/check_socials \
+  -H "Content-Type: application/json" \
+  -d '{"name": "myproject", "platforms": ["github", "twitter"]}'
+
+# Bulk search 50 domains
+curl -X POST http://localhost:3000/bulk_search \
+  -H "Content-Type: application/json" \
+  -d '{"domains": ["name1", "name2", "name3"], "tld": "com"}'
+```
+
+#### JavaScript/Node.js Local Server Integration
+
+```javascript
+// Complete local server integration example
+
+const BASE_URL = 'http://localhost:3000';
+
+// Initialize connection to local domain-search server
+async function initializeDomainSearch() {
+  try {
+    // Test server connection
+    const response = await fetch(`${BASE_URL}/search_domain`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        domain_name: 'test-connection',
+        tlds: ['com']
+      })
+    });
+
+    if (response.ok) {
+      console.log('✅ Domain Search server connected');
+      return true;
+    }
+    throw new Error('Server not responding');
+  } catch (error) {
+    console.error('❌ Failed to connect to server:', error.message);
+    console.error('Make sure to run: npm start');
+    return false;
+  }
+}
+
+// Usage
+const connected = await initializeDomainSearch();
+if (connected) {
+  // Proceed with domain searches
+  const result = await fetch(`${BASE_URL}/search_domain`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      domain_name: 'vibecoding',
+      tlds: ['com', 'io', 'dev']
+    })
+  }).then(r => r.json());
+
+  console.log(`Found ${result.results.filter(r => r.available).length} available domains`);
+}
+```
+
 ## Development
 
 ### Setup
@@ -2295,28 +2942,54 @@ try {
 
 ### Workflow 1: Complete Domain Acquisition with Partial Availability Handling
 
-A comprehensive workflow that handles scenarios where domains are available on some registrars but not others, or when some checks succeed while others fail:
+A comprehensive workflow that integrates `search_domain`, `check_socials`, and `suggest_domains` to validate a brand name across domain registrars and social media platforms simultaneously, with full error handling for partial availability scenarios:
 
 ```typescript
-async function completeDomainAcquisition(brandName: string) {
+// Types for the workflow response
+interface AcquisitionReport {
+  brandName: string;
+  summary: {
+    domainsChecked: number;
+    available: number;
+    taken: number;
+    failedChecks: number;
+    socialsAvailable: number;
+    socialsTaken: number;
+    socialsUnverified: number;
+  };
+  domains: {
+    available: Array<{ domain: string; price: number; registrar: string }>;
+    taken: string[];
+    alternatives: Array<{ domain: string; price: number; variant: string }>;
+  };
+  socials: {
+    available: Array<{ platform: string; confidence: string; url: string }>;
+    taken: Array<{ platform: string; url: string }>;
+    needsManualCheck: Array<{ platform: string; url: string; reason: string }>;
+  };
+  pricing: Array<{ domain: string; bestRegistrar: string; price: number }>;
+  nextSteps: string[];
+  presentation: string;  // Formatted for user display
+}
+
+async function completeDomainAcquisition(brandName: string): Promise<AcquisitionReport> {
+  console.log(`\n🔍 Starting brand validation for "${brandName}"...\n`);
+
   // Step 1: Run parallel checks across domains and social media
   const [domainResults, socialResults] = await Promise.all([
     searchDomain({
       domain_name: brandName,
       tlds: ["com", "io", "dev", "app", "co"]
     }),
-    checkSocials({
-      name: brandName,
-      platforms: ["github", "twitter", "instagram", "npm", "linkedin"]
-    })
+    checkSocialsWithErrorHandling(brandName)  // Use wrapper for better error handling
   ]);
 
-  // Step 2: Handle partial availability - some TLDs available, some taken
+  // Step 2: Handle partial domain availability
   const available = domainResults.results.filter(r => r.available && !r.error);
   const taken = domainResults.results.filter(r => !r.available && !r.error);
   const failed = domainResults.results.filter(r => r.error);
 
-  // Step 3: Retry failed checks with exponential backoff
+  // Step 3: Retry failed domain checks with exponential backoff
   const retriedResults = [];
   for (const failedDomain of failed) {
     const tld = failedDomain.domain.split('.').pop();
@@ -2334,25 +3007,26 @@ async function completeDomainAcquisition(brandName: string) {
           break;
         }
       } catch (e) {
-        delay *= 2; // Exponential backoff
+        delay *= 2;
       }
     }
   }
 
-  // Step 4: If preferred .com is taken, generate alternatives
+  // Step 4: If preferred .com is taken, use suggest_domains for alternatives
   let suggestions = [];
   const comDomain = [...available, ...retriedResults].find(d => d.domain.endsWith('.com'));
   if (!comDomain) {
+    // Use suggest_domains (not smart) to get variations of the exact name
     const suggestResult = await suggestDomains({
       base_name: brandName,
       tld: "com",
       max_suggestions: 10,
-      variants: ["prefixes", "suffixes", "hyphen"]
+      variants: ["prefixes", "suffixes", "hyphen"]  // Most common patterns
     });
     suggestions = suggestResult.suggestions;
   }
 
-  // Step 5: Compare pricing for available domains
+  // Step 5: Compare pricing for top available domains
   const priceComparisons = await Promise.all(
     available.slice(0, 3).map(d => {
       const [name, tld] = d.domain.split('.');
@@ -2360,63 +3034,266 @@ async function completeDomainAcquisition(brandName: string) {
     })
   );
 
-  // Step 6: Compile comprehensive report
-  return {
+  // Step 6: Process social media results with platform-specific handling
+  const socialReport = processSocialResults(socialResults, brandName);
+
+  // Step 7: Compile comprehensive report
+  const report: AcquisitionReport = {
     brandName,
     summary: {
       domainsChecked: domainResults.results.length,
       available: available.length + retriedResults.length,
       taken: taken.length,
       failedChecks: failed.length - retriedResults.length,
-      socialsAvailable: socialResults.results.filter(r => r.available).length
+      socialsAvailable: socialReport.available.length,
+      socialsTaken: socialReport.taken.length,
+      socialsUnverified: socialReport.needsManualCheck.length
     },
     domains: {
       available: [...available, ...retriedResults].map(d => ({
         domain: d.domain,
         price: d.price_first_year,
-        registrar: d.registrar,
-        source: d.source
+        registrar: d.registrar
       })),
       taken: taken.map(d => d.domain),
-      alternatives: suggestions.map(s => s.domain)
-    },
-    socials: {
-      available: socialResults.results
-        .filter(r => r.available && r.confidence !== "low")
-        .map(r => r.platform),
-      taken: socialResults.results
-        .filter(r => !r.available)
-        .map(r => r.platform),
-      needsManualCheck: socialResults.results
-        .filter(r => r.confidence === "low")
-        .map(r => r.platform)
+      alternatives: suggestions.map(s => ({
+        domain: s.domain,
+        price: s.price_first_year,
+        variant: s.variant_type
+      }))
     },
+    socials: socialReport,
     pricing: priceComparisons.filter(Boolean).map(p => ({
       domain: p.domain,
-      bestPrice: p.best_first_year,
-      recommendation: p.recommendation
+      bestRegistrar: p.best_first_year?.registrar,
+      price: p.best_first_year?.price
     })),
-    nextSteps: generateNextSteps(available, socialResults, suggestions)
+    nextSteps: generateNextSteps(available, socialReport, suggestions),
+    presentation: ""  // Will be filled below
   };
+
+  // Step 8: Generate formatted presentation for user
+  report.presentation = formatReportForPresentation(report);
+
+  return report;
 }
 
-function generateNextSteps(available, socialResults, suggestions) {
+// Social media check with comprehensive error handling per platform
+async function checkSocialsWithErrorHandling(brandName: string) {
+  try {
+    const result = await checkSocials({
+      name: brandName,
+      platforms: ["github", "twitter", "instagram", "npm", "linkedin"]
+    });
+    return result;
+  } catch (error) {
+    // Return partial results even if some platforms fail
+    return {
+      results: [
+        { platform: "github", available: null, error: error.message, confidence: "low" },
+        { platform: "twitter", available: null, error: error.message, confidence: "low" },
+        { platform: "instagram", available: null, error: "Platform blocks automated checks", confidence: "low" },
+        { platform: "npm", available: null, error: error.message, confidence: "low" },
+        { platform: "linkedin", available: null, error: "Platform blocks automated checks", confidence: "low" }
+      ]
+    };
+  }
+}
+
+// Process social results with platform-specific error handling
+function processSocialResults(socialResults: any, brandName: string) {
+  const available = [];
+  const taken = [];
+  const needsManualCheck = [];
+
+  for (const result of socialResults.results) {
+    const platformUrl = getPlatformUrl(result.platform, brandName);
+
+    if (result.error) {
+      // Platform-specific error handling
+      needsManualCheck.push({
+        platform: result.platform,
+        url: platformUrl,
+        reason: getErrorReason(result.platform, result.error)
+      });
+    } else if (result.confidence === "low") {
+      // Low confidence results need manual verification
+      needsManualCheck.push({
+        platform: result.platform,
+        url: platformUrl,
+        reason: "Automated check unreliable - verify manually"
+      });
+    } else if (result.available) {
+      available.push({
+        platform: result.platform,
+        confidence: result.confidence,
+        url: platformUrl
+      });
+    } else {
+      taken.push({
+        platform: result.platform,
+        url: platformUrl
+      });
+    }
+  }
+
+  return { available, taken, needsManualCheck };
+}
+
+// Get direct URL for each platform
+function getPlatformUrl(platform: string, username: string): string {
+  const urls = {
+    github: `https://github.com/${username}`,
+    twitter: `https://twitter.com/${username}`,
+    instagram: `https://instagram.com/${username}`,
+    npm: `https://www.npmjs.com/~${username}`,
+    linkedin: `https://linkedin.com/in/${username}`,
+    reddit: `https://reddit.com/user/${username}`,
+    youtube: `https://youtube.com/@${username}`,
+    tiktok: `https://tiktok.com/@${username}`,
+    producthunt: `https://producthunt.com/@${username}`,
+    pypi: `https://pypi.org/user/${username}`
+  };
+  return urls[platform] || `https://${platform}.com/${username}`;
+}
+
+// Get human-readable error reason per platform
+function getErrorReason(platform: string, error: string): string {
+  const reasons = {
+    instagram: "Instagram blocks automated checks - visit link to verify",
+    linkedin: "LinkedIn requires login to check profiles",
+    tiktok: "TikTok blocks automated checks - visit link to verify",
+    twitter: error.includes("rate") ? "Twitter rate limited - try again in 15 min" : "Twitter check failed",
+    github: error.includes("rate") ? "GitHub rate limited - try again later" : "GitHub check failed"
+  };
+  return reasons[platform] || `Check failed: ${error}`;
+}
+
+function generateNextSteps(available, socialReport, suggestions) {
   const steps = [];
+
+  // Domain recommendations
   if (available.length > 0) {
-    steps.push(`Register ${available[0].domain} at ${available[0].registrar}`);
+    const best = available.sort((a, b) => a.price - b.price)[0];
+    steps.push(`1. Register ${best.domain} at ${best.registrar} ($${best.price}/yr)`);
   } else if (suggestions.length > 0) {
-    steps.push(`Consider alternative: ${suggestions[0].domain}`);
+    steps.push(`1. Consider alternative: ${suggestions[0].domain} ($${suggestions[0].price}/yr)`);
+  }
+
+  // Social media recommendations
+  if (socialReport.available.length > 0) {
+    const platforms = socialReport.available.map(s => s.platform).join(", ");
+    steps.push(`2. Secure username on: ${platforms}`);
   }
-  const availableSocials = socialResults.results.filter(r => r.available);
-  if (availableSocials.length > 0) {
-    steps.push(`Secure username on: ${availableSocials.map(r => r.platform).join(', ')}`);
+
+  if (socialReport.needsManualCheck.length > 0) {
+    steps.push(`3. Manually verify: ${socialReport.needsManualCheck.map(s => s.platform).join(", ")}`);
   }
+
   return steps;
 }
 
-// Usage
-const acquisition = await completeDomainAcquisition("techstartup");
-// Returns comprehensive report with partial availability handled
+// Format report for user-friendly presentation
+function formatReportForPresentation(report: AcquisitionReport): string {
+  const lines = [
+    ``,
+    `${"═".repeat(60)}`,
+    `  BRAND VALIDATION REPORT: ${report.brandName.toUpperCase()}`,
+    `${"═".repeat(60)}`,
+    ``,
+    `📊 SUMMARY`,
+    `${"─".repeat(40)}`,
+    `  Domains:  ${report.summary.available} available / ${report.summary.taken} taken`,
+    `  Socials:  ${report.summary.socialsAvailable} available / ${report.summary.socialsTaken} taken`,
+    `  Unverified: ${report.summary.socialsUnverified} platforms need manual check`,
+    ``
+  ];
+
+  // Available domains section
+  if (report.domains.available.length > 0) {
+    lines.push(`✅ AVAILABLE DOMAINS`);
+    lines.push(`${"─".repeat(40)}`);
+    report.domains.available.forEach(d => {
+      lines.push(`  ${d.domain.padEnd(25)} $${d.price}/yr  (${d.registrar})`);
+    });
+    lines.push(``);
+  }
+
+  // Alternatives section
+  if (report.domains.alternatives.length > 0) {
+    lines.push(`💡 SUGGESTED ALTERNATIVES`);
+    lines.push(`${"─".repeat(40)}`);
+    report.domains.alternatives.slice(0, 5).forEach(d => {
+      lines.push(`  ${d.domain.padEnd(25)} $${d.price}/yr  (${d.variant})`);
+    });
+    lines.push(``);
+  }
+
+  // Social media section
+  lines.push(`📱 SOCIAL MEDIA`);
+  lines.push(`${"─".repeat(40)}`);
+  report.socials.available.forEach(s => {
+    lines.push(`  ✅ ${s.platform.padEnd(12)} Available (${s.confidence} confidence)`);
+  });
+  report.socials.taken.forEach(s => {
+    lines.push(`  ❌ ${s.platform.padEnd(12)} Taken`);
+  });
+  report.socials.needsManualCheck.forEach(s => {
+    lines.push(`  ⚠️  ${s.platform.padEnd(12)} ${s.reason}`);
+  });
+  lines.push(``);
+
+  // Next steps
+  lines.push(`🚀 NEXT STEPS`);
+  lines.push(`${"─".repeat(40)}`);
+  report.nextSteps.forEach(step => lines.push(`  ${step}`));
+  lines.push(``);
+  lines.push(`${"═".repeat(60)}`);
+
+  return lines.join("\n");
+}
+
+// Usage example
+const report = await completeDomainAcquisition("techstartup");
+console.log(report.presentation);
+
+// Example output:
+// ════════════════════════════════════════════════════════════
+//   BRAND VALIDATION REPORT: TECHSTARTUP
+// ════════════════════════════════════════════════════════════
+//
+// 📊 SUMMARY
+// ────────────────────────────────────────
+//   Domains:  3 available / 2 taken
+//   Socials:  2 available / 1 taken
+//   Unverified: 2 platforms need manual check
+//
+// ✅ AVAILABLE DOMAINS
+// ────────────────────────────────────────
+//   techstartup.io            $29.88/yr  (porkbun)
+//   techstartup.dev           $10.18/yr  (porkbun)
+//   techstartup.app           $12.00/yr  (porkbun)
+//
+// 💡 SUGGESTED ALTERNATIVES
+// ────────────────────────────────────────
+//   gettechstartup.com        $8.95/yr   (prefixes)
+//   techstartupnow.com        $8.95/yr   (suffixes)
+//
+// 📱 SOCIAL MEDIA
+// ────────────────────────────────────────
+//   ✅ github       Available (high confidence)
+//   ✅ npm          Available (high confidence)
+//   ❌ twitter      Taken
+//   ⚠️  instagram    Instagram blocks automated checks - visit link to verify
+//   ⚠️  linkedin     LinkedIn requires login to check profiles
+//
+// 🚀 NEXT STEPS
+// ────────────────────────────────────────
+//   1. Register techstartup.dev at porkbun ($10.18/yr)
+//   2. Secure username on: github, npm
+//   3. Manually verify: instagram, linkedin
+//
+// ════════════════════════════════════════════════════════════
 ```
 
 ### Workflow 2: Domain Suggestion When Preferred Name is Taken

package/package.json

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