Domain Search MCP

Instructions

Implementation Reference

• src/tools/suggest_domains.ts:208-284 (handler)

  Main execution function for the suggest_domains tool. Parses input, generates domain variations using helpers, checks availability via searchDomain, scores suggestions, filters available ones, and formats response with insights.

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

• src/tools/suggest_domains.ts:17-41 (schema)

  Zod schema for validating input to the suggest_domains tool.

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

• src/tools/suggest_domains.ts:48-88 (registration)

  MCP tool registration object defining name, description, and input schema for suggest_domains.

  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'],
    },
  };

• src/server.ts:184-192 (registration)

  Server dispatch logic that routes 'suggest_domains' tool calls to the executeSuggestDomains handler.

  case 'suggest_domains':
    return executeSuggestDomains({
      base_name: args.base_name as string,
      tld: (args.tld as string) || 'com',
      variants: args.variants as
        | Array<'hyphen' | 'numbers' | 'abbreviations' | 'synonyms' | 'prefixes' | 'suffixes'>
        | undefined,
      max_suggestions: (args.max_suggestions as number) || 10,
    });

• src/types.ts:276-281 (schema)

  TypeScript interface defining the input shape for suggest_domains.

  export interface SuggestDomainsInput {
    base_name: string;
    tld?: string;
    variants?: ('hyphen' | 'numbers' | 'abbreviations' | 'synonyms')[];
    max_suggestions?: number;
  }