domain-search-mcp 1.0.0

package/src/tools/search_domain.ts

@@ -0,0 +1,93 @@
+/**
+ * search_domain Tool - Primary Domain Search.
+ *
+ * This is the main entry point for domain availability checks.
+ * Designed for magic first moment: works with zero configuration.
+ */
+
+import { z } from 'zod';
+import type { SearchResponse } from '../types.js';
+import { searchDomain } from '../services/domain-search.js';
+import { wrapError } from '../utils/errors.js';
+
+/**
+ * Input schema for search_domain.
+ */
+export const searchDomainSchema = z.object({
+  domain_name: z
+    .string()
+    .min(1)
+    .max(63)
+    .describe(
+      "The domain name you want to check (e.g., 'vibecoding', 'myapp'). Don't include the extension (.com, .io, etc.)",
+    ),
+  tlds: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "TLD extensions to check (e.g., ['com', 'io', 'dev']). Defaults to ['com', 'io', 'dev'] if not specified.",
+    ),
+  registrars: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Optional: specific registrars to check (e.g., ['porkbun', 'namecheap']). Leave empty to auto-select.",
+    ),
+});
+
+export type SearchDomainInput = z.infer<typeof searchDomainSchema>;
+
+/**
+ * Tool definition for MCP.
+ */
+export const searchDomainTool = {
+  name: 'search_domain',
+  description: `Search for domain availability and pricing across multiple TLDs.
+
+Returns:
+- Availability status for each domain
+- Pricing (first year and renewal)
+- Whether WHOIS privacy is included
+- Human-readable insights and next steps
+
+Examples:
+- search_domain("vibecoding") → checks vibecoding.com, .io, .dev
+- search_domain("myapp", ["com", "io"]) → checks specific TLDs`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      domain_name: {
+        type: 'string',
+        description:
+          "The domain name to search (e.g., 'vibecoding'). No extension needed.",
+      },
+      tlds: {
+        type: 'array',
+        items: { type: 'string' },
+        description:
+          "TLD extensions to check (e.g., ['com', 'io', 'dev']). Defaults to ['com', 'io', 'dev'].",
+      },
+      registrars: {
+        type: 'array',
+        items: { type: 'string' },
+        description:
+          "Optional: specific registrars to check. Leave empty to auto-select.",
+      },
+    },
+    required: ['domain_name'],
+  },
+};
+
+/**
+ * Execute the search_domain tool.
+ */
+export async function executeSearchDomain(
+  input: SearchDomainInput,
+): Promise<SearchResponse> {
+  try {
+    const { domain_name, tlds, registrars } = searchDomainSchema.parse(input);
+    return await searchDomain(domain_name, tlds, registrars);
+  } catch (error) {
+    throw wrapError(error);
+  }
+}

package/src/tools/suggest_domains.ts

@@ -0,0 +1,284 @@
+/**
+ * suggest_domains Tool - Domain Name Suggestions.
+ *
+ * Generate and check variations of a base domain name.
+ * Helps find available alternatives when the primary name is taken.
+ */
+
+import { z } from 'zod';
+import { searchDomain } from '../services/domain-search.js';
+import { validateDomainName } from '../utils/validators.js';
+import { wrapError } from '../utils/errors.js';
+import type { DomainResult } from '../types.js';
+
+/**
+ * Input schema for suggest_domains.
+ */
+export const suggestDomainsSchema = z.object({
+  base_name: z
+    .string()
+    .min(1)
+    .describe("The base domain name to generate variations from (e.g., 'vibecoding')."),
+  tld: z
+    .string()
+    .optional()
+    .default('com')
+    .describe("TLD to check suggestions against (e.g., 'com'). Defaults to 'com'."),
+  variants: z
+    .array(z.enum(['hyphen', 'numbers', 'abbreviations', 'synonyms', 'prefixes', 'suffixes']))
+    .optional()
+    .describe(
+      "Types of variations to generate. Defaults to all types.",
+    ),
+  max_suggestions: z
+    .number()
+    .int()
+    .min(1)
+    .max(50)
+    .optional()
+    .default(10)
+    .describe("Maximum number of suggestions to return (1-50). Defaults to 10."),
+});
+
+export type SuggestDomainsInput = z.infer<typeof suggestDomainsSchema>;
+
+/**
+ * Tool definition for MCP.
+ */
+export const suggestDomainsTool = {
+  name: 'suggest_domains',
+  description: `Generate and check availability of domain name variations.
+
+Creates variations like:
+- Hyphenated: vibe-coding
+- With numbers: vibecoding1, vibecoding2
+- Prefixes: getvibecoding, tryvibecoding
+- Suffixes: vibecodingapp, vibecodinghq
+
+Returns only available suggestions, ranked by quality.
+
+Example:
+- suggest_domains("vibecoding") → finds available variations`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      base_name: {
+        type: 'string',
+        description: "The base domain name to generate variations from.",
+      },
+      tld: {
+        type: 'string',
+        description: "TLD to check (e.g., 'com'). Defaults to 'com'.",
+      },
+      variants: {
+        type: 'array',
+        items: {
+          type: 'string',
+          enum: ['hyphen', 'numbers', 'abbreviations', 'synonyms', 'prefixes', 'suffixes'],
+        },
+        description: "Types of variations to generate. Defaults to all.",
+      },
+      max_suggestions: {
+        type: 'number',
+        description: "Maximum suggestions to return (1-50). Defaults to 10.",
+      },
+    },
+    required: ['base_name'],
+  },
+};
+
+/**
+ * Generate domain name variations.
+ */
+function generateVariations(
+  baseName: string,
+  variantTypes: string[],
+): string[] {
+  const variations = new Set<string>();
+
+  // Always include the original
+  variations.add(baseName);
+
+  if (variantTypes.includes('hyphen') || variantTypes.length === 0) {
+    // Add hyphens at word boundaries (heuristic: before capital letters or common words)
+    const hyphenated = baseName.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+    if (hyphenated !== baseName) {
+      variations.add(hyphenated);
+    }
+
+    // Try hyphen in the middle
+    if (baseName.length >= 6) {
+      const mid = Math.floor(baseName.length / 2);
+      variations.add(baseName.slice(0, mid) + '-' + baseName.slice(mid));
+    }
+  }
+
+  if (variantTypes.includes('numbers') || variantTypes.length === 0) {
+    // Add numbers
+    for (let i = 1; i <= 3; i++) {
+      variations.add(`${baseName}${i}`);
+    }
+    variations.add(`${baseName}io`);
+    variations.add(`${baseName}app`);
+  }
+
+  if (variantTypes.includes('prefixes') || variantTypes.length === 0) {
+    const prefixes = ['get', 'try', 'use', 'my', 'the', 'go', 'hey', 'hi'];
+    for (const prefix of prefixes) {
+      variations.add(`${prefix}${baseName}`);
+    }
+  }
+
+  if (variantTypes.includes('suffixes') || variantTypes.length === 0) {
+    const suffixes = ['app', 'hq', 'io', 'labs', 'dev', 'ai', 'hub', 'now'];
+    for (const suffix of suffixes) {
+      variations.add(`${baseName}${suffix}`);
+    }
+  }
+
+  if (variantTypes.includes('abbreviations') || variantTypes.length === 0) {
+    // Remove vowels (except first letter)
+    const abbreviated = baseName[0] + baseName.slice(1).replace(/[aeiou]/gi, '');
+    if (abbreviated.length >= 3 && abbreviated !== baseName) {
+      variations.add(abbreviated);
+    }
+  }
+
+  return Array.from(variations);
+}
+
+/**
+ * Score a domain suggestion.
+ * Higher score = better suggestion.
+ */
+function scoreSuggestion(
+  original: string,
+  suggestion: string,
+  result: DomainResult,
+): number {
+  let score = 50; // Base score
+
+  // Prefer shorter names
+  score -= suggestion.length;
+
+  // Prefer exact match
+  if (suggestion === original) score += 20;
+
+  // Prefer no hyphens
+  if (!suggestion.includes('-')) score += 5;
+
+  // Prefer no numbers
+  if (!/\d/.test(suggestion)) score += 5;
+
+  // Prefer cheaper prices
+  if (result.price_first_year !== null) {
+    if (result.price_first_year <= 10) score += 10;
+    else if (result.price_first_year <= 15) score += 5;
+  }
+
+  // Penalize premiums
+  if (result.premium) score -= 20;
+
+  // Bonus for privacy included
+  if (result.privacy_included) score += 5;
+
+  return score;
+}
+
+/**
+ * Response format for suggestions.
+ */
+interface SuggestDomainsResponse {
+  base_name: string;
+  tld: string;
+  total_checked: number;
+  available_count: number;
+  suggestions: Array<{
+    domain: string;
+    price_first_year: number | null;
+    registrar: string;
+    score: number;
+  }>;
+  insights: string[];
+}
+
+/**
+ * Execute the suggest_domains tool.
+ */
+export async function executeSuggestDomains(
+  input: SuggestDomainsInput,
+): Promise<SuggestDomainsResponse> {
+  try {
+    const { base_name, tld, variants, max_suggestions } =
+      suggestDomainsSchema.parse(input);
+
+    const normalizedBase = validateDomainName(base_name);
+    const variantTypes = variants || [];
+
+    // Generate variations
+    const variations = generateVariations(normalizedBase, variantTypes);
+
+    // Limit to max + some buffer for unavailable ones
+    const toCheck = variations.slice(0, max_suggestions * 2);
+
+    // Check availability for all variations
+    const results: Array<{ name: string; result: DomainResult | null }> = [];
+
+    for (const name of toCheck) {
+      try {
+        const response = await searchDomain(name, [tld]);
+        const result = response.results.find((r) => r.domain === `${name}.${tld}`);
+        results.push({ name, result: result || null });
+      } catch {
+        results.push({ name, result: null });
+      }
+    }
+
+    // Filter to available and score them
+    const available = results
+      .filter((r) => r.result?.available)
+      .map((r) => ({
+        name: r.name,
+        result: r.result!,
+        score: scoreSuggestion(normalizedBase, r.name, r.result!),
+      }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, max_suggestions);
+
+    const insights: string[] = [];
+
+    if (available.length > 0) {
+      insights.push(
+        `✅ Found ${available.length} available variation${available.length > 1 ? 's' : ''}`,
+      );
+
+      const best = available[0]!;
+      insights.push(
+        `⭐ Top suggestion: ${best.name}.${tld} ($${best.result.price_first_year ?? 'unknown'}/year)`,
+      );
+    } else {
+      insights.push(
+        `❌ No available variations found for ${normalizedBase}.${tld}`,
+      );
+      insights.push(
+        '💡 Try a different TLD or modify the base name more significantly',
+      );
+    }
+
+    return {
+      base_name: normalizedBase,
+      tld,
+      total_checked: toCheck.length,
+      available_count: available.length,
+      suggestions: available.map((a) => ({
+        domain: `${a.name}.${tld}`,
+        price_first_year: a.result.price_first_year,
+        registrar: a.result.registrar,
+        score: a.score,
+      })),
+      insights,
+    };
+  } catch (error) {
+    throw wrapError(error);
+  }
+}

package/src/tools/tld_info.ts

@@ -0,0 +1,294 @@
+/**
+ * tld_info Tool - TLD Information.
+ *
+ * Get information about a Top Level Domain (TLD).
+ * Includes pricing, restrictions, and recommendations.
+ */
+
+import { z } from 'zod';
+import type { TLDInfo } from '../types.js';
+import { validateTld } from '../utils/validators.js';
+import { wrapError } from '../utils/errors.js';
+import { tldCache, tldCacheKey } from '../utils/cache.js';
+
+/**
+ * Input schema for tld_info.
+ */
+export const tldInfoSchema = z.object({
+  tld: z
+    .string()
+    .min(2)
+    .max(63)
+    .describe("The TLD to get information about (e.g., 'com', 'io', 'dev')."),
+  detailed: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("Whether to include detailed information. Defaults to false."),
+});
+
+export type TldInfoInput = z.infer<typeof tldInfoSchema>;
+
+/**
+ * Tool definition for MCP.
+ */
+export const tldInfoTool = {
+  name: 'tld_info',
+  description: `Get information about a Top Level Domain (TLD).
+
+Returns:
+- Description and typical use case
+- Price range
+- Any special restrictions
+- Popularity and recommendations
+
+Example:
+- tld_info("io") → info about .io domains`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      tld: {
+        type: 'string',
+        description: "The TLD to get info about (e.g., 'com', 'io', 'dev').",
+      },
+      detailed: {
+        type: 'boolean',
+        description: "Include detailed information. Defaults to false.",
+      },
+    },
+    required: ['tld'],
+  },
+};
+
+/**
+ * Static TLD database.
+ */
+const TLD_DATABASE: Record<string, TLDInfo> = {
+  com: {
+    tld: 'com',
+    description: 'Commercial - the most recognized TLD worldwide',
+    typical_use: 'Businesses, commercial websites, general purpose',
+    price_range: { min: 8.88, max: 15.99, currency: 'USD' },
+    renewal_price_typical: 12.99,
+    restrictions: [],
+    popularity: 'high',
+    category: 'generic',
+  },
+  io: {
+    tld: 'io',
+    description: 'British Indian Ocean Territory - popular with tech startups',
+    typical_use: 'Tech startups, SaaS products, developer tools',
+    price_range: { min: 29.88, max: 59.99, currency: 'USD' },
+    renewal_price_typical: 44.99,
+    restrictions: [],
+    popularity: 'high',
+    category: 'country',
+  },
+  dev: {
+    tld: 'dev',
+    description: 'Developer - for software developers and their projects',
+    typical_use: 'Developer portfolios, tools, documentation sites',
+    price_range: { min: 10.18, max: 19.99, currency: 'USD' },
+    renewal_price_typical: 14.99,
+    restrictions: ['Requires HTTPS (HSTS preloaded)'],
+    popularity: 'medium',
+    category: 'new',
+  },
+  app: {
+    tld: 'app',
+    description: 'Application - for mobile and web applications',
+    typical_use: 'Mobile apps, web applications, software products',
+    price_range: { min: 11.18, max: 19.99, currency: 'USD' },
+    renewal_price_typical: 14.99,
+    restrictions: ['Requires HTTPS (HSTS preloaded)'],
+    popularity: 'medium',
+    category: 'new',
+  },
+  co: {
+    tld: 'co',
+    description: 'Colombia / Company - popular alternative to .com',
+    typical_use: 'Companies, startups, short URLs',
+    price_range: { min: 9.48, max: 29.99, currency: 'USD' },
+    renewal_price_typical: 24.99,
+    restrictions: [],
+    popularity: 'high',
+    category: 'country',
+  },
+  net: {
+    tld: 'net',
+    description: 'Network - originally for network providers',
+    typical_use: 'Technology companies, network services, ISPs',
+    price_range: { min: 9.88, max: 14.99, currency: 'USD' },
+    renewal_price_typical: 12.99,
+    restrictions: [],
+    popularity: 'high',
+    category: 'generic',
+  },
+  org: {
+    tld: 'org',
+    description: 'Organization - for non-profits and communities',
+    typical_use: 'Non-profit organizations, open source projects, communities',
+    price_range: { min: 9.88, max: 14.99, currency: 'USD' },
+    renewal_price_typical: 12.99,
+    restrictions: [],
+    popularity: 'high',
+    category: 'generic',
+  },
+  ai: {
+    tld: 'ai',
+    description: 'Anguilla / Artificial Intelligence - trending for AI projects',
+    typical_use: 'AI/ML projects, tech startups, research',
+    price_range: { min: 49.88, max: 99.99, currency: 'USD' },
+    renewal_price_typical: 79.99,
+    restrictions: [],
+    popularity: 'medium',
+    category: 'country',
+  },
+  xyz: {
+    tld: 'xyz',
+    description: 'XYZ - for the next generation of internet users',
+    typical_use: 'Creative projects, personal sites, unconventional brands',
+    price_range: { min: 1.99, max: 12.99, currency: 'USD' },
+    renewal_price_typical: 12.99,
+    restrictions: [],
+    popularity: 'medium',
+    category: 'new',
+  },
+  me: {
+    tld: 'me',
+    description: 'Montenegro - popular for personal brands',
+    typical_use: 'Personal websites, portfolios, URL shorteners',
+    price_range: { min: 9.88, max: 19.99, currency: 'USD' },
+    renewal_price_typical: 17.99,
+    restrictions: [],
+    popularity: 'medium',
+    category: 'country',
+  },
+  sh: {
+    tld: 'sh',
+    description: 'Saint Helena - popular with developers (shell scripts)',
+    typical_use: 'Developer tools, CLI applications, tech projects',
+    price_range: { min: 29.88, max: 49.99, currency: 'USD' },
+    renewal_price_typical: 44.99,
+    restrictions: [],
+    popularity: 'low',
+    category: 'country',
+  },
+  cc: {
+    tld: 'cc',
+    description: 'Cocos Islands - often used as "Creative Commons"',
+    typical_use: 'Creative projects, alternative to .com',
+    price_range: { min: 9.88, max: 24.99, currency: 'USD' },
+    renewal_price_typical: 19.99,
+    restrictions: [],
+    popularity: 'low',
+    category: 'country',
+  },
+};
+
+/**
+ * Response format for TLD info.
+ */
+interface TldInfoResponse extends TLDInfo {
+  insights: string[];
+  recommendation: string;
+}
+
+/**
+ * Execute the tld_info tool.
+ */
+export async function executeTldInfo(
+  input: TldInfoInput,
+): Promise<TldInfoResponse> {
+  try {
+    const { tld, detailed } = tldInfoSchema.parse(input);
+    const normalizedTld = validateTld(tld);
+
+    // Check cache
+    const cacheKey = tldCacheKey(normalizedTld);
+    const cached = tldCache.get(cacheKey);
+    if (cached) {
+      return formatResponse(cached, detailed);
+    }
+
+    // Look up in database
+    const info = TLD_DATABASE[normalizedTld];
+
+    if (!info) {
+      // Return generic info for unknown TLDs
+      const genericInfo: TLDInfo = {
+        tld: normalizedTld,
+        description: `${normalizedTld.toUpperCase()} domain extension`,
+        typical_use: 'General purpose',
+        price_range: { min: 10, max: 50, currency: 'USD' },
+        renewal_price_typical: 20,
+        restrictions: ['Check registrar for specific restrictions'],
+        popularity: 'low',
+        category: 'generic',
+      };
+
+      return formatResponse(genericInfo, detailed);
+    }
+
+    // Cache the result
+    tldCache.set(cacheKey, info);
+
+    return formatResponse(info, detailed);
+  } catch (error) {
+    throw wrapError(error);
+  }
+}
+
+/**
+ * Format the response with insights.
+ */
+function formatResponse(info: TLDInfo, detailed: boolean): TldInfoResponse {
+  const insights: string[] = [];
+  let recommendation = '';
+
+  // Generate insights
+  if (info.popularity === 'high') {
+    insights.push(`✅ .${info.tld} is highly recognized and trusted`);
+  } else if (info.popularity === 'medium') {
+    insights.push(`💡 .${info.tld} is gaining popularity in specific niches`);
+  } else {
+    insights.push(`⚠️ .${info.tld} is less common - may need more brand building`);
+  }
+
+  if (info.restrictions.length > 0) {
+    insights.push(`⚠️ Special requirements: ${info.restrictions.join(', ')}`);
+  }
+
+  if (info.price_range.min <= 10) {
+    insights.push(`💰 Budget-friendly starting at $${info.price_range.min}/year`);
+  } else if (info.price_range.min >= 40) {
+    insights.push(`💸 Premium pricing starting at $${info.price_range.min}/year`);
+  }
+
+  // Generate recommendation
+  switch (info.tld) {
+    case 'com':
+      recommendation = 'Best for mainstream businesses and maximum recognition';
+      break;
+    case 'io':
+      recommendation = 'Perfect for tech startups and SaaS products';
+      break;
+    case 'dev':
+      recommendation = 'Ideal for developers and tech portfolios (requires HTTPS)';
+      break;
+    case 'app':
+      recommendation = 'Great for mobile/web applications (requires HTTPS)';
+      break;
+    case 'ai':
+      recommendation = 'Trending choice for AI/ML projects, but pricey';
+      break;
+    default:
+      recommendation = `Good choice for ${info.typical_use.toLowerCase()}`;
+  }
+
+  return {
+    ...info,
+    insights,
+    recommendation,
+  };
+}