domain-search-mcp 1.0.0

package/src/registrars/porkbun.ts

@@ -0,0 +1,380 @@
+/**
+ * Porkbun Registrar Adapter.
+ *
+ * Porkbun offers competitive pricing and a JSON API.
+ * API Docs: https://porkbun.com/api/json/v3/documentation
+ */
+
+import axios, { type AxiosInstance, type AxiosError } from 'axios';
+import { z } from 'zod';
+import { RegistrarAdapter } from './base.js';
+import type { DomainResult, TLDInfo } from '../types.js';
+import { config } from '../config.js';
+import { logger } from '../utils/logger.js';
+import {
+  AuthenticationError,
+  RateLimitError,
+  RegistrarApiError,
+} from '../utils/errors.js';
+
+const PORKBUN_API_BASE = 'https://api.porkbun.com/api/json/v3';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Zod Schemas for API Response Validation
+// SECURITY: Validate all external API responses to prevent unexpected data
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Base response schema - all Porkbun responses have this structure.
+ */
+const PorkbunBaseResponseSchema = z.object({
+  status: z.enum(['SUCCESS', 'ERROR']),
+  message: z.string().optional(),
+});
+
+/**
+ * Domain availability check response schema.
+ */
+const PorkbunCheckResponseSchema = PorkbunBaseResponseSchema.extend({
+  avail: z.number().optional(),  // 1 = available, 0 = taken
+  premium: z.number().optional(), // 1 = premium
+  yourPrice: z.string().optional(),
+  retailPrice: z.string().optional(),
+});
+
+/**
+ * Pricing response schema for a single TLD.
+ */
+const PorkbunTldPricingSchema = z.object({
+  registration: z.string(),
+  renewal: z.string(),
+  transfer: z.string(),
+  coupons: z.object({
+    registration: z.object({
+      code: z.string(),
+      max_per_user: z.number(),
+      first_year_only: z.string(),
+      type: z.string(),
+      amount: z.number(),
+    }).optional(),
+  }).optional(),
+});
+
+/**
+ * Full pricing response schema.
+ */
+const PorkbunPricingResponseSchema = PorkbunBaseResponseSchema.extend({
+  pricing: z.record(z.string(), PorkbunTldPricingSchema).optional(),
+});
+
+// Type inference from schemas
+type PorkbunBaseResponse = z.infer<typeof PorkbunBaseResponseSchema>;
+type PorkbunCheckResponse = z.infer<typeof PorkbunCheckResponseSchema>;
+type PorkbunPricingResponse = z.infer<typeof PorkbunPricingResponseSchema>;
+
+/**
+ * Porkbun adapter implementation.
+ */
+export class PorkbunAdapter extends RegistrarAdapter {
+  readonly name = 'Porkbun';
+  readonly id = 'porkbun';
+
+  private readonly client: AxiosInstance;
+  private readonly apiKey?: string;
+  private readonly apiSecret?: string;
+  private pricingCache: Record<string, { registration: number; renewal: number; transfer: number }> = {};
+
+  constructor() {
+    // Porkbun has generous rate limits, ~60/min is safe
+    super(60);
+
+    this.apiKey = config.porkbun.apiKey;
+    this.apiSecret = config.porkbun.apiSecret;
+
+    this.client = axios.create({
+      baseURL: PORKBUN_API_BASE,
+      timeout: this.timeoutMs,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+  }
+
+  /**
+   * Check if Porkbun API is enabled.
+   */
+  isEnabled(): boolean {
+    return config.porkbun.enabled;
+  }
+
+  /**
+   * Search for domain availability.
+   */
+  async search(domain: string, tld: string): Promise<DomainResult> {
+    if (!this.isEnabled()) {
+      throw new AuthenticationError(
+        'porkbun',
+        'API credentials not configured',
+      );
+    }
+
+    const fullDomain = `${domain}.${tld}`;
+    logger.debug('Porkbun search', { domain: fullDomain });
+
+    try {
+      // First, try to get pricing (this is cached)
+      const pricing = await this.getPricing(tld);
+
+      // Then check availability
+      const availability = await this.checkAvailability(domain, tld);
+
+      return this.createResult(domain, tld, {
+        available: availability.available,
+        premium: availability.premium,
+        price_first_year: availability.price ?? pricing?.registration ?? null,
+        price_renewal: pricing?.renewal ?? null,
+        transfer_price: pricing?.transfer ?? null,
+        privacy_included: true, // Porkbun includes WHOIS privacy
+        source: 'porkbun_api',
+        premium_reason: availability.premium ? 'Premium domain' : undefined,
+      });
+    } catch (error) {
+      this.handleApiError(error, fullDomain);
+      throw error; // Re-throw if not handled
+    }
+  }
+
+  /**
+   * Check domain availability.
+   * SECURITY: Validates API response with Zod schema.
+   */
+  private async checkAvailability(
+    domain: string,
+    tld: string,
+  ): Promise<{ available: boolean; premium: boolean; price?: number }> {
+    const result = await this.retryWithBackoff(async () => {
+      const response = await this.client.post(
+        '/domain/check',
+        {
+          apikey: this.apiKey,
+          secretapikey: this.apiSecret,
+          domain: `${domain}.${tld}`,
+        },
+      );
+
+      // Validate response with Zod schema
+      const parseResult = PorkbunCheckResponseSchema.safeParse(response.data);
+      if (!parseResult.success) {
+        logger.warn('Porkbun API response validation failed', {
+          domain: `${domain}.${tld}`,
+          errors: parseResult.error.errors,
+        });
+        throw new RegistrarApiError(
+          this.name,
+          'Invalid API response format',
+        );
+      }
+
+      const validated = parseResult.data;
+
+      if (validated.status !== 'SUCCESS') {
+        throw new RegistrarApiError(
+          this.name,
+          validated.message || 'Unknown error',
+        );
+      }
+
+      return validated;
+    }, `check ${domain}.${tld}`);
+
+    return {
+      available: result.avail === 1,
+      premium: result.premium === 1,
+      price: result.yourPrice ? parseFloat(result.yourPrice) : undefined,
+    };
+  }
+
+  /**
+   * Get pricing for a TLD.
+   * SECURITY: Validates API response with Zod schema.
+   */
+  private async getPricing(
+    tld: string,
+  ): Promise<{ registration: number; renewal: number; transfer: number } | null> {
+    // Check cache first
+    if (this.pricingCache[tld]) {
+      return this.pricingCache[tld];
+    }
+
+    try {
+      const result = await this.retryWithBackoff(async () => {
+        const response = await this.client.post(
+          '/pricing/get',
+          {
+            apikey: this.apiKey,
+            secretapikey: this.apiSecret,
+          },
+        );
+
+        // Validate response with Zod schema
+        const parseResult = PorkbunPricingResponseSchema.safeParse(response.data);
+        if (!parseResult.success) {
+          logger.warn('Porkbun pricing API response validation failed', {
+            errors: parseResult.error.errors,
+          });
+          throw new RegistrarApiError(
+            this.name,
+            'Invalid pricing API response format',
+          );
+        }
+
+        const validated = parseResult.data;
+
+        if (validated.status !== 'SUCCESS') {
+          throw new RegistrarApiError(
+            this.name,
+            validated.message || 'Failed to get pricing',
+          );
+        }
+
+        return validated.pricing;
+      }, 'get pricing');
+
+      if (result) {
+        // Cache all TLD pricing
+        for (const [tldKey, prices] of Object.entries(result)) {
+          this.pricingCache[tldKey] = {
+            registration: parseFloat(prices.registration),
+            renewal: parseFloat(prices.renewal),
+            transfer: parseFloat(prices.transfer),
+          };
+        }
+      }
+
+      return this.pricingCache[tld] || null;
+    } catch (error) {
+      logger.warn('Failed to get Porkbun pricing', {
+        tld,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  }
+
+  /**
+   * Get TLD information.
+   */
+  async getTldInfo(tld: string): Promise<TLDInfo | null> {
+    const pricing = await this.getPricing(tld);
+    if (!pricing) return null;
+
+    return {
+      tld,
+      description: `${tld.toUpperCase()} domain`,
+      typical_use: this.getTldUseCase(tld),
+      price_range: {
+        min: pricing.registration,
+        max: pricing.registration,
+        currency: 'USD',
+      },
+      renewal_price_typical: pricing.renewal,
+      restrictions: [],
+      popularity: this.getTldPopularity(tld),
+      category: this.getTldCategory(tld),
+    };
+  }
+
+  /**
+   * Handle API errors with user-friendly messages.
+   */
+  private handleApiError(error: unknown, domain: string): never {
+    if (axios.isAxiosError(error)) {
+      const axiosError = error as AxiosError<PorkbunBaseResponse>;
+
+      if (axiosError.response) {
+        const status = axiosError.response.status;
+        const message =
+          axiosError.response.data?.message || axiosError.message;
+
+        if (status === 401 || status === 403) {
+          throw new AuthenticationError('porkbun', message);
+        }
+
+        if (status === 429) {
+          const retryAfter = axiosError.response.headers['retry-after'];
+          throw new RateLimitError(
+            'porkbun',
+            retryAfter ? parseInt(retryAfter, 10) : undefined,
+          );
+        }
+
+        throw new RegistrarApiError(this.name, message, status, error);
+      }
+
+      if (axiosError.code === 'ECONNABORTED') {
+        throw new RegistrarApiError(
+          this.name,
+          `Request timed out for ${domain}`,
+          undefined,
+          error,
+        );
+      }
+    }
+
+    throw new RegistrarApiError(
+      this.name,
+      error instanceof Error ? error.message : 'Unknown error',
+      undefined,
+      error instanceof Error ? error : undefined,
+    );
+  }
+
+  /**
+   * Get typical use case for a TLD.
+   */
+  private getTldUseCase(tld: string): string {
+    const useCases: Record<string, string> = {
+      com: 'General commercial websites',
+      io: 'Tech startups and SaaS products',
+      dev: 'Developer tools and portfolios',
+      app: 'Mobile and web applications',
+      co: 'Companies and startups',
+      net: 'Network services and utilities',
+      org: 'Non-profit organizations',
+      ai: 'AI and machine learning projects',
+      xyz: 'Creative and unconventional projects',
+    };
+    return useCases[tld] || 'General purpose';
+  }
+
+  /**
+   * Get TLD popularity rating.
+   */
+  private getTldPopularity(tld: string): 'high' | 'medium' | 'low' {
+    const highPopularity = ['com', 'net', 'org', 'io', 'co'];
+    const mediumPopularity = ['dev', 'app', 'ai', 'me'];
+
+    if (highPopularity.includes(tld)) return 'high';
+    if (mediumPopularity.includes(tld)) return 'medium';
+    return 'low';
+  }
+
+  /**
+   * Get TLD category.
+   */
+  private getTldCategory(tld: string): TLDInfo['category'] {
+    const countryTlds = ['uk', 'de', 'fr', 'jp', 'cn', 'au', 'ca', 'us'];
+    const sponsoredTlds = ['edu', 'gov', 'mil'];
+    const newTlds = ['io', 'dev', 'app', 'ai', 'xyz', 'tech', 'cloud'];
+
+    if (countryTlds.includes(tld)) return 'country';
+    if (sponsoredTlds.includes(tld)) return 'sponsored';
+    if (newTlds.includes(tld)) return 'new';
+    return 'generic';
+  }
+}
+
+/**
+ * Singleton instance.
+ */
+export const porkbunAdapter = new PorkbunAdapter();

package/src/server.ts

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+/**
+ * Domain Search MCP Server.
+ *
+ * Model Context Protocol server for domain availability search.
+ * Supports Porkbun, Namecheap, RDAP, and WHOIS as data sources.
+ *
+ * Features:
+ * - search_domain: Check availability across multiple TLDs
+ * - bulk_search: Check many domains at once
+ * - compare_registrars: Compare pricing across registrars
+ * - suggest_domains: Generate available name variations
+ * - tld_info: Get TLD information and recommendations
+ * - check_socials: Check social handle availability
+ *
+ * @see https://github.com/yourusername/domain-search-mcp
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  type Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { config, getAvailableSources, hasRegistrarApi } from './config.js';
+import { logger, generateRequestId, setRequestId, clearRequestId } from './utils/logger.js';
+import { wrapError, DomainSearchError } from './utils/errors.js';
+import {
+  searchDomainTool,
+  executeSearchDomain,
+  bulkSearchTool,
+  executeBulkSearch,
+  compareRegistrarsTool,
+  executeCompareRegistrars,
+  suggestDomainsTool,
+  executeSuggestDomains,
+  tldInfoTool,
+  executeTldInfo,
+  checkSocialsTool,
+  executeCheckSocials,
+} from './tools/index.js';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Server Configuration
+// ═══════════════════════════════════════════════════════════════════════════
+
+const SERVER_NAME = 'domain-search-mcp';
+const SERVER_VERSION = '1.0.0';
+
+/**
+ * All available tools.
+ */
+const TOOLS: Tool[] = [
+  searchDomainTool as Tool,
+  bulkSearchTool as Tool,
+  compareRegistrarsTool as Tool,
+  suggestDomainsTool as Tool,
+  tldInfoTool as Tool,
+  checkSocialsTool as Tool,
+];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Server Implementation
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create and configure the MCP server.
+ */
+function createServer(): Server {
+  const server = new Server(
+    {
+      name: SERVER_NAME,
+      version: SERVER_VERSION,
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    },
+  );
+
+  // Register tool listing handler
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+  });
+
+  // Register tool call handler
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const requestId = generateRequestId();
+
+    try {
+      setRequestId(requestId);
+      logger.info('Tool call started', { tool: name, request_id: requestId });
+
+      const result = await executeToolCall(name, args || {});
+
+      logger.info('Tool call completed', {
+        tool: name,
+        request_id: requestId,
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      const wrapped = wrapError(error);
+
+      logger.error('Tool call failed', {
+        tool: name,
+        request_id: requestId,
+        error: wrapped.message,
+        code: wrapped.code,
+      });
+
+      // Return error as content (MCP pattern)
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                error: true,
+                code: wrapped.code,
+                message: wrapped.userMessage,
+                retryable: wrapped.retryable,
+                suggestedAction: wrapped.suggestedAction,
+              },
+              null,
+              2,
+            ),
+          },
+        ],
+        isError: true,
+      };
+    } finally {
+      clearRequestId();
+    }
+  });
+
+  return server;
+}
+
+/**
+ * Execute a tool call by name.
+ */
+async function executeToolCall(
+  name: string,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  switch (name) {
+    case 'search_domain':
+      return executeSearchDomain({
+        domain_name: args.domain_name as string,
+        tlds: args.tlds as string[] | undefined,
+        registrars: args.registrars as string[] | undefined,
+      });
+
+    case 'bulk_search':
+      return executeBulkSearch({
+        domains: args.domains as string[],
+        tld: (args.tld as string) || 'com',
+        registrar: args.registrar as string | undefined,
+      });
+
+    case 'compare_registrars':
+      return executeCompareRegistrars({
+        domain: args.domain as string,
+        tld: args.tld as string,
+        registrars: args.registrars as string[] | undefined,
+      });
+
+    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,
+      });
+
+    case 'tld_info':
+      return executeTldInfo({
+        tld: args.tld as string,
+        detailed: (args.detailed as boolean) || false,
+      });
+
+    case 'check_socials':
+      return executeCheckSocials({
+        name: args.name as string,
+        platforms: args.platforms as
+          | Array<'github' | 'twitter' | 'instagram' | 'linkedin' | 'tiktok'>
+          | undefined,
+      });
+
+    default:
+      throw new DomainSearchError(
+        'UNKNOWN_TOOL',
+        `Unknown tool: ${name}`,
+        `The tool "${name}" is not available.`,
+        {
+          retryable: false,
+          suggestedAction: `Available tools: ${TOOLS.map((t) => t.name).join(', ')}`,
+        },
+      );
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Startup
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Main entry point.
+ */
+async function main(): Promise<void> {
+  // Log startup info
+  logger.info('Domain Search MCP starting', {
+    version: SERVER_VERSION,
+    node_version: process.version,
+    sources: getAvailableSources(),
+    has_registrar_api: hasRegistrarApi(),
+    dry_run: config.dryRun,
+  });
+
+  // Warn if no API keys configured
+  if (!hasRegistrarApi()) {
+    logger.warn(
+      'No registrar API keys configured. Falling back to RDAP/WHOIS only.',
+    );
+    logger.warn(
+      'For pricing info, add PORKBUN_API_KEY and PORKBUN_API_SECRET to your .env file.',
+    );
+  }
+
+  // Create and start server
+  const server = createServer();
+  const transport = new StdioServerTransport();
+
+  await server.connect(transport);
+
+  logger.info('Domain Search MCP ready', {
+    tools: TOOLS.length,
+    transport: 'stdio',
+  });
+
+  // Handle graceful shutdown
+  process.on('SIGINT', async () => {
+    logger.info('Shutting down...');
+    await server.close();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', async () => {
+    logger.info('Shutting down...');
+    await server.close();
+    process.exit(0);
+  });
+}
+
+// Run the server
+main().catch((error) => {
+  logger.error('Failed to start server', {
+    error: error instanceof Error ? error.message : String(error),
+    stack: error instanceof Error ? error.stack : undefined,
+  });
+  process.exit(1);
+});