domain-search-mcp 1.0.0

package/src/tools/check_socials.ts

@@ -0,0 +1,467 @@
+/**
+ * check_socials Tool - Social Handle Availability.
+ *
+ * Check if a username is available across social platforms.
+ * Uses Sherlock-style detection for accurate results.
+ *
+ * Detection methods:
+ * - status_code: 404 = available, 200 = taken
+ * - message: Check response body for error indicators
+ * - api: Use platform's public API
+ */
+
+import { z } from 'zod';
+import axios from 'axios';
+import type { SocialPlatform, SocialHandleResult } from '../types.js';
+import { wrapError } from '../utils/errors.js';
+import { logger } from '../utils/logger.js';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Platform Configuration (Sherlock-style)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Detection method types (inspired by Sherlock).
+ */
+type ErrorType = 'status_code' | 'message' | 'api';
+
+/**
+ * Platform configuration for username checking.
+ */
+interface PlatformConfig {
+  /** URL to check (use {} for username placeholder) */
+  url: string;
+  /** Public profile URL */
+  profileUrl: string;
+  /** Detection method */
+  errorType: ErrorType;
+  /** For message type: strings that indicate username is available */
+  errorMsg?: string[];
+  /** For status_code type: HTTP status that means available */
+  errorCode?: number;
+  /** Expected confidence level */
+  confidence: 'high' | 'medium' | 'low';
+  /** HTTP method */
+  method: 'GET' | 'HEAD';
+  /** Custom headers */
+  headers?: Record<string, string>;
+  /** Username regex validation */
+  regexCheck?: RegExp;
+}
+
+/**
+ * Platform configurations using Sherlock-style detection.
+ * HIGH confidence = public API or reliable status codes
+ * MEDIUM confidence = status codes but may have edge cases
+ * LOW confidence = platforms that block automated checks
+ */
+const PLATFORM_CONFIGS: Record<SocialPlatform, PlatformConfig> = {
+  // ─────────────────────────────────────────────────────────────────────────
+  // HIGH CONFIDENCE (Public APIs)
+  // ─────────────────────────────────────────────────────────────────────────
+  github: {
+    url: 'https://api.github.com/users/{}',
+    profileUrl: 'https://github.com/{}',
+    errorType: 'status_code',
+    errorCode: 404,
+    confidence: 'high',
+    method: 'GET',
+    headers: {
+      'Accept': 'application/vnd.github.v3+json',
+      'User-Agent': 'Domain-Search-MCP/1.0',
+    },
+    regexCheck: /^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$/i,
+  },
+
+  npm: {
+    url: 'https://registry.npmjs.org/{}',
+    profileUrl: 'https://www.npmjs.com/~{}',
+    errorType: 'status_code',
+    errorCode: 404,
+    confidence: 'high',
+    method: 'GET',
+    headers: {
+      'Accept': 'application/json',
+    },
+    regexCheck: /^[a-z0-9][a-z0-9._-]*$/i,
+  },
+
+  pypi: {
+    url: 'https://pypi.org/user/{}/',
+    profileUrl: 'https://pypi.org/user/{}/',
+    errorType: 'status_code',
+    errorCode: 404,
+    confidence: 'high',
+    method: 'GET',
+  },
+
+  reddit: {
+    url: 'https://www.reddit.com/user/{}/about.json',
+    profileUrl: 'https://reddit.com/user/{}',
+    errorType: 'message',
+    errorMsg: ['"error": 404'],
+    confidence: 'high',
+    method: 'GET',
+    headers: {
+      'User-Agent': 'Domain-Search-MCP/1.0 (checking username availability)',
+    },
+    regexCheck: /^[A-Za-z0-9_-]{3,20}$/,
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // MEDIUM CONFIDENCE (Status codes, some edge cases)
+  // ─────────────────────────────────────────────────────────────────────────
+  twitter: {
+    url: 'https://twitter.com/{}',
+    profileUrl: 'https://twitter.com/{}',
+    errorType: 'status_code',
+    errorCode: 404,
+    confidence: 'medium',
+    method: 'HEAD',
+    headers: {
+      'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
+    },
+    regexCheck: /^[A-Za-z0-9_]{1,15}$/,
+  },
+
+  youtube: {
+    url: 'https://www.youtube.com/@{}',
+    profileUrl: 'https://youtube.com/@{}',
+    errorType: 'status_code',
+    errorCode: 404,
+    confidence: 'medium',
+    method: 'HEAD',
+    headers: {
+      'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
+    },
+  },
+
+  producthunt: {
+    url: 'https://www.producthunt.com/@{}',
+    profileUrl: 'https://producthunt.com/@{}',
+    errorType: 'status_code',
+    errorCode: 404,
+    confidence: 'medium',
+    method: 'HEAD',
+    headers: {
+      'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
+    },
+  },
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // LOW CONFIDENCE (Aggressive bot protection)
+  // ─────────────────────────────────────────────────────────────────────────
+  instagram: {
+    url: 'https://www.instagram.com/{}/',
+    profileUrl: 'https://instagram.com/{}',
+    errorType: 'status_code',
+    errorCode: 404,
+    confidence: 'low', // Instagram aggressively blocks automated checks
+    method: 'HEAD',
+    headers: {
+      'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
+    },
+    regexCheck: /^[a-zA-Z0-9_.]{1,30}$/,
+  },
+
+  linkedin: {
+    url: 'https://www.linkedin.com/in/{}',
+    profileUrl: 'https://linkedin.com/in/{}',
+    errorType: 'status_code',
+    errorCode: 404,
+    confidence: 'low', // LinkedIn requires auth
+    method: 'HEAD',
+    headers: {
+      'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
+    },
+  },
+
+  tiktok: {
+    url: 'https://www.tiktok.com/@{}',
+    profileUrl: 'https://tiktok.com/@{}',
+    errorType: 'status_code',
+    errorCode: 404,
+    confidence: 'low', // TikTok blocks automated checks
+    method: 'HEAD',
+    headers: {
+      'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
+    },
+    regexCheck: /^[a-zA-Z0-9_.]{2,24}$/,
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Zod Schema
+// ═══════════════════════════════════════════════════════════════════════════
+
+const ALL_PLATFORMS = [
+  'github', 'twitter', 'instagram', 'linkedin', 'tiktok',
+  'reddit', 'youtube', 'npm', 'pypi', 'producthunt',
+] as const;
+
+/**
+ * Input schema for check_socials.
+ */
+export const checkSocialsSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .max(30)
+    .describe("The username/handle to check (e.g., 'vibecoding')."),
+  platforms: z
+    .array(z.enum(ALL_PLATFORMS))
+    .optional()
+    .describe(
+      "Platforms to check. Defaults to ['github', 'twitter', 'reddit', 'npm'].",
+    ),
+});
+
+export type CheckSocialsInput = z.infer<typeof checkSocialsSchema>;
+
+/**
+ * Tool definition for MCP.
+ */
+export const checkSocialsTool = {
+  name: 'check_socials',
+  description: `Check if a username is available on social media and developer platforms.
+
+Supports 10 platforms with varying confidence levels:
+- HIGH: GitHub, npm, PyPI, Reddit (reliable public APIs)
+- MEDIUM: Twitter/X, YouTube, ProductHunt (status code based)
+- LOW: Instagram, LinkedIn, TikTok (block automated checks - verify manually)
+
+Returns availability status with confidence indicator.
+
+Example:
+- check_socials("vibecoding") → checks GitHub, Twitter, Reddit, npm
+- check_socials("myapp", ["github", "npm", "pypi"]) → developer platforms only`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: "The username/handle to check.",
+      },
+      platforms: {
+        type: 'array',
+        items: {
+          type: 'string',
+          enum: ALL_PLATFORMS,
+        },
+        description:
+          "Platforms to check. Defaults to ['github', 'twitter', 'reddit', 'npm'].",
+      },
+    },
+    required: ['name'],
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Platform Checking Logic
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check a single platform using Sherlock-style detection.
+ */
+async function checkPlatform(
+  username: string,
+  platform: SocialPlatform,
+): Promise<SocialHandleResult> {
+  const config = PLATFORM_CONFIGS[platform];
+  const url = config.url.replace('{}', username);
+  const profileUrl = config.profileUrl.replace('{}', username);
+
+  // Validate username format if regex provided
+  if (config.regexCheck && !config.regexCheck.test(username)) {
+    return {
+      platform,
+      handle: username,
+      available: false,
+      url: profileUrl,
+      checked_at: new Date().toISOString(),
+      confidence: 'high', // High confidence it's invalid
+    };
+  }
+
+  try {
+    const response = await axios({
+      method: config.method,
+      url,
+      timeout: 8000,
+      validateStatus: () => true, // Don't throw on any status
+      headers: {
+        ...config.headers,
+      },
+      maxRedirects: 0,
+    });
+
+    let available = false;
+
+    // Determine availability based on errorType
+    switch (config.errorType) {
+      case 'status_code':
+        available = response.status === (config.errorCode ?? 404);
+        break;
+
+      case 'message':
+        if (config.errorMsg && typeof response.data === 'string') {
+          available = config.errorMsg.some((msg) =>
+            response.data.includes(msg),
+          );
+        } else if (config.errorMsg && typeof response.data === 'object') {
+          const dataStr = JSON.stringify(response.data);
+          available = config.errorMsg.some((msg) => dataStr.includes(msg));
+        }
+        break;
+
+      case 'api':
+        // API-specific logic would go here
+        available = response.status === 404;
+        break;
+    }
+
+    return {
+      platform,
+      handle: username,
+      available,
+      url: profileUrl,
+      checked_at: new Date().toISOString(),
+      confidence: config.confidence,
+    };
+  } catch (error) {
+    logger.debug(`Failed to check ${platform}`, {
+      username,
+      error: error instanceof Error ? error.message : String(error),
+    });
+
+    // Return uncertain result on error
+    return {
+      platform,
+      handle: username,
+      available: false, // Assume taken if we can't check
+      url: profileUrl,
+      checked_at: new Date().toISOString(),
+      confidence: 'low',
+    };
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Response Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Response format for social checks.
+ */
+interface CheckSocialsResponse {
+  name: string;
+  results: SocialHandleResult[];
+  summary: {
+    available: number;
+    taken: number;
+    uncertain: number;
+  };
+  insights: string[];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Main Execution
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Execute the check_socials tool.
+ */
+export async function executeCheckSocials(
+  input: CheckSocialsInput,
+): Promise<CheckSocialsResponse> {
+  try {
+    const { name, platforms } = checkSocialsSchema.parse(input);
+
+    // Default platforms: mix of social and developer platforms
+    const platformsToCheck: SocialPlatform[] = platforms || [
+      'github',
+      'twitter',
+      'reddit',
+      'npm',
+    ];
+
+    // Normalize username (lowercase, remove special chars)
+    const normalizedName = name.toLowerCase().replace(/[^a-z0-9_-]/g, '');
+
+    // Check all platforms in parallel (max 5 concurrent)
+    const results = await Promise.all(
+      platformsToCheck.map((p) => checkPlatform(normalizedName, p)),
+    );
+
+    // Categorize results by confidence
+    const highConfidence = results.filter((r) => r.confidence === 'high');
+    const available = results.filter(
+      (r) => r.available && r.confidence !== 'low',
+    );
+    const taken = results.filter((r) => !r.available && r.confidence !== 'low');
+    const uncertain = results.filter((r) => r.confidence === 'low');
+
+    // Generate insights
+    const insights: string[] = [];
+
+    if (available.length > 0) {
+      insights.push(
+        `✅ "${normalizedName}" is available on: ${available.map((r) => r.platform).join(', ')}`,
+      );
+    }
+
+    if (taken.length > 0) {
+      insights.push(
+        `❌ "${normalizedName}" is taken on: ${taken.map((r) => r.platform).join(', ')}`,
+      );
+    }
+
+    if (uncertain.length > 0) {
+      insights.push(
+        `⚠️ Could not reliably check: ${uncertain.map((r) => r.platform).join(', ')} (verify manually)`,
+      );
+    }
+
+    // Developer-focused insight
+    const devPlatforms = results.filter((r) =>
+      ['github', 'npm', 'pypi'].includes(r.platform),
+    );
+    const allDevAvailable = devPlatforms.every((r) => r.available);
+    if (devPlatforms.length > 0 && allDevAvailable) {
+      insights.push(
+        `🛠️ Great for developers! "${normalizedName}" is available on all dev platforms`,
+      );
+    }
+
+    // Branding consistency advice
+    const allAvailable = results.every((r) => r.available);
+    const allTaken = results.every((r) => !r.available);
+
+    if (allAvailable) {
+      insights.push(
+        `🎉 Perfect! "${normalizedName}" is available everywhere - grab it now!`,
+      );
+    } else if (allTaken) {
+      insights.push(
+        `💡 Try variations: ${normalizedName}hq, ${normalizedName}app, get${normalizedName}, ${normalizedName}io`,
+      );
+    } else if (available.length > 0 && taken.length > 0) {
+      insights.push(
+        '💡 For consistent branding, consider a name available on all platforms',
+      );
+    }
+
+    return {
+      name: normalizedName,
+      results,
+      summary: {
+        available: available.length,
+        taken: taken.length,
+        uncertain: uncertain.length,
+      },
+      insights,
+    };
+  } catch (error) {
+    throw wrapError(error);
+  }
+}

package/src/tools/compare_registrars.ts

@@ -0,0 +1,162 @@
+/**
+ * compare_registrars Tool - Price Comparison.
+ *
+ * Compare pricing across multiple registrars for a specific domain.
+ * Helps find the best deal.
+ */
+
+import { z } from 'zod';
+import { compareRegistrars } from '../services/domain-search.js';
+import { validateDomainName, validateTld } from '../utils/validators.js';
+import { wrapError } from '../utils/errors.js';
+import type { DomainResult } from '../types.js';
+
+/**
+ * Input schema for compare_registrars.
+ */
+export const compareRegistrarsSchema = z.object({
+  domain: z
+    .string()
+    .min(1)
+    .describe("The domain name to compare (e.g., 'vibecoding')."),
+  tld: z
+    .string()
+    .describe("The TLD extension (e.g., 'com', 'io')."),
+  registrars: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Registrars to compare (e.g., ['porkbun', 'namecheap']). Defaults to all available.",
+    ),
+});
+
+export type CompareRegistrarsInput = z.infer<typeof compareRegistrarsSchema>;
+
+/**
+ * Tool definition for MCP.
+ */
+export const compareRegistrarsTool = {
+  name: 'compare_registrars',
+  description: `Compare domain pricing across multiple registrars.
+
+Checks the same domain at different registrars to find:
+- Best first year price
+- Best renewal price
+- Overall recommendation
+
+Returns pricing comparison and a recommendation.
+
+Example:
+- compare_registrars("vibecoding", "com") → compares Porkbun vs Namecheap`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      domain: {
+        type: 'string',
+        description: "The domain name to compare (without extension).",
+      },
+      tld: {
+        type: 'string',
+        description: "The TLD extension (e.g., 'com', 'io').",
+      },
+      registrars: {
+        type: 'array',
+        items: { type: 'string' },
+        description:
+          "Registrars to compare. Defaults to ['porkbun', 'namecheap'].",
+      },
+    },
+    required: ['domain', 'tld'],
+  },
+};
+
+/**
+ * Response format for registrar comparison.
+ */
+interface CompareRegistrarsResponse {
+  domain: string;
+  what_happened: string;
+  comparison_count: number;
+  comparisons: DomainResult[];
+  best_first_year: {
+    registrar: string;
+    price: number;
+    currency: string;
+  } | null;
+  best_renewal: {
+    registrar: string;
+    price: number;
+    currency: string;
+  } | null;
+  recommendation: string;
+  insights: string[];
+}
+
+/**
+ * Execute the compare_registrars tool.
+ */
+export async function executeCompareRegistrars(
+  input: CompareRegistrarsInput,
+): Promise<CompareRegistrarsResponse> {
+  try {
+    const { domain, tld, registrars } = compareRegistrarsSchema.parse(input);
+
+    const normalizedDomain = validateDomainName(domain);
+    const normalizedTld = validateTld(tld);
+    const fullDomain = `${normalizedDomain}.${normalizedTld}`;
+
+    const result = await compareRegistrars(
+      normalizedDomain,
+      normalizedTld,
+      registrars,
+    );
+
+    const insights: string[] = [];
+
+    // Generate insights
+    if (result.best_first_year && result.best_renewal) {
+      if (result.best_first_year.registrar === result.best_renewal.registrar) {
+        insights.push(
+          `✅ ${result.best_first_year.registrar} wins on both first year and renewal`,
+        );
+      } else {
+        insights.push(
+          `💡 Split strategy: ${result.best_first_year.registrar} for year 1, consider transfer to ${result.best_renewal.registrar} later`,
+        );
+      }
+    }
+
+    // Check for privacy inclusion
+    const withPrivacy = result.comparisons.filter((r) => r.privacy_included);
+    if (withPrivacy.length > 0) {
+      insights.push(
+        `🔒 ${withPrivacy.map((r) => r.registrar).join(', ')} include free WHOIS privacy`,
+      );
+    }
+
+    // Premium warning
+    const premiums = result.comparisons.filter((r) => r.premium);
+    if (premiums.length > 0) {
+      insights.push(
+        `⚠️ This is a premium domain at: ${premiums.map((r) => r.registrar).join(', ')}`,
+      );
+    }
+
+    return {
+      domain: fullDomain,
+      what_happened: `Compared pricing across ${result.comparisons.length} registrars`,
+      comparison_count: result.comparisons.length,
+      comparisons: result.comparisons,
+      best_first_year: result.best_first_year
+        ? { ...result.best_first_year, currency: 'USD' }
+        : null,
+      best_renewal: result.best_renewal
+        ? { ...result.best_renewal, currency: 'USD' }
+        : null,
+      recommendation: result.recommendation,
+      insights,
+    };
+  } catch (error) {
+    throw wrapError(error);
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,45 @@
+/**
+ * Tool Exports.
+ */
+
+export {
+  searchDomainTool,
+  searchDomainSchema,
+  executeSearchDomain,
+  type SearchDomainInput,
+} from './search_domain.js';
+
+export {
+  bulkSearchTool,
+  bulkSearchSchema,
+  executeBulkSearch,
+  type BulkSearchInput,
+} from './bulk_search.js';
+
+export {
+  compareRegistrarsTool,
+  compareRegistrarsSchema,
+  executeCompareRegistrars,
+  type CompareRegistrarsInput,
+} from './compare_registrars.js';
+
+export {
+  suggestDomainsTool,
+  suggestDomainsSchema,
+  executeSuggestDomains,
+  type SuggestDomainsInput,
+} from './suggest_domains.js';
+
+export {
+  tldInfoTool,
+  tldInfoSchema,
+  executeTldInfo,
+  type TldInfoInput,
+} from './tld_info.js';
+
+export {
+  checkSocialsTool,
+  checkSocialsSchema,
+  executeCheckSocials,
+  type CheckSocialsInput,
+} from './check_socials.js';