Domain Search MCP

Instructions

Implementation Reference

• src/tools/tld_info.ts:200-240 (handler)

  Main execution function for the tld_info tool. Validates input, checks cache, looks up TLD info from static database or generates generic info, caches result, and formats response.

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

• src/tools/tld_info.ts:17-30 (schema)

  Zod input schema for validating tld_info tool parameters: tld (required string) and optional detailed boolean.

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

• src/tools/tld_info.ts:35-61 (registration)

  Tool definition object for 'tld_info' including name, description, and inputSchema, used for MCP registration.

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

• src/tools/tld_info.ts:245-294 (helper)

  Helper function to format TLD info response with generated insights and recommendation based on TLD properties.

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

• src/server.ts:206-210 (registration)

  Dispatch handler in server that routes 'tld_info' tool calls to the executeTldInfo function.

  case 'tld_info':
    return executeTldInfo({
      tld: args.tld as string,
      detailed: (args.detailed as boolean) || false,
    });