Domain Search MCP

Instructions

Implementation Reference

• src/tools/compare_registrars.ts:98-162 (handler)

  Handler function that executes the compare_registrars tool: validates input, normalizes domain/TLD, calls the core compareRegistrars service, generates insights (privacy, premium warnings, recommendations), and returns formatted response.

  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);
    }
  }

• src/tools/compare_registrars.ts:17-31 (schema)

  Zod validation schema defining input for compare_registrars tool: domain (string), tld (string), optional registrars array.

  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.",
      ),
  });

• src/server.ts:58-66 (registration)

  Registration of the compare_registrars tool in the MCP server's TOOLS array, imported as compareRegistrarsTool.

  const TOOLS: Tool[] = [
    searchDomainTool as Tool,
    bulkSearchTool as Tool,
    compareRegistrarsTool as Tool,
    suggestDomainsTool as Tool,
    suggestDomainsSmartTool as Tool,
    tldInfoTool as Tool,
    checkSocialsTool as Tool,
  ];

• src/server.ts:177-182 (registration)

  Dispatch/execution routing for 'compare_registrars' tool call in the server's executeToolCall switch statement.

  case 'compare_registrars':
    return executeCompareRegistrars({
      domain: args.domain as string,
      tld: args.tld as string,
      registrars: args.registrars as string[] | undefined,
    });

• src/services/domain-search.ts:514-583 (helper)

  Core service function compareRegistrars that performs the actual registrar price comparison by querying each specified registrar via searchSingleDomain, finds best first-year and renewal prices, generates recommendation.

  export async function compareRegistrars(
    domain: string,
    tld: string,
    registrars: string[] = ['porkbun', 'namecheap'],
  ): Promise<{
    comparisons: DomainResult[];
    best_first_year: { registrar: string; price: number } | null;
    best_renewal: { registrar: string; price: number } | null;
    recommendation: string;
  }> {
    const normalizedDomain = validateDomainName(domain);
    const comparisons: DomainResult[] = [];
  
    // Check each registrar
    for (const registrar of registrars) {
      try {
        const { result } = await searchSingleDomain(normalizedDomain, tld, [
          registrar,
        ]);
        comparisons.push(result);
      } catch (error) {
        logger.warn(`Registrar ${registrar} comparison failed`, {
          domain: `${normalizedDomain}.${tld}`,
          error: error instanceof Error ? error.message : String(error),
        });
      }
    }
  
    // Find best prices
    let bestFirstYear: { registrar: string; price: number } | null = null;
    let bestRenewal: { registrar: string; price: number } | null = null;
  
    for (const result of comparisons) {
      if (result.available && result.price_first_year !== null) {
        if (!bestFirstYear || result.price_first_year < bestFirstYear.price) {
          bestFirstYear = {
            registrar: result.registrar,
            price: result.price_first_year,
          };
        }
      }
      if (result.available && result.price_renewal !== null) {
        if (!bestRenewal || result.price_renewal < bestRenewal.price) {
          bestRenewal = {
            registrar: result.registrar,
            price: result.price_renewal,
          };
        }
      }
    }
  
    // Generate recommendation
    let recommendation = 'Could not compare registrars';
    if (bestFirstYear && bestRenewal) {
      if (bestFirstYear.registrar === bestRenewal.registrar) {
        recommendation = `${bestFirstYear.registrar} offers the best price for both first year ($${bestFirstYear.price}) and renewal ($${bestRenewal.price})`;
      } else {
        recommendation = `${bestFirstYear.registrar} for first year ($${bestFirstYear.price}), ${bestRenewal.registrar} for renewal ($${bestRenewal.price})`;
      }
    } else if (bestFirstYear) {
      recommendation = `${bestFirstYear.registrar} has the best first year price: $${bestFirstYear.price}`;
    }
  
    return {
      comparisons,
      best_first_year: bestFirstYear,
      best_renewal: bestRenewal,
      recommendation,
    };
  }