Hunter.io MCP Server

Instructions

Implementation Reference

• src/index.ts:521-555 (handler)

  The main execution logic for the 'hunter_domain_search' tool. Validates input using isDomainSearchParams, calls Hunter.io /domain-search API with retry logic, and returns the response or error.

  case 'hunter_domain_search': {
    if (!isDomainSearchParams(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for hunter_domain_search'
      );
    }
  
    try {
      // Hunter.io API expects query parameters for domain search
      const response = await withRetry(
        async () => apiClient.get('/domain-search', { params: args }),
        'domain search'
      );
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response.data, null, 2),
          },
        ],
        isError: false,
      };
    } catch (error) {
      const errorMessage = axios.isAxiosError(error)
        ? `API Error: ${error.response?.data?.message || error.message}`
        : `Error: ${error instanceof Error ? error.message : String(error)}`;
  
      return {
        content: [{ type: 'text', text: errorMessage }],
        isError: true,
      };
    }
  }

• src/index.ts:65-94 (schema)

  Tool definition for 'hunter_domain_search' including name, description, and input schema specifying parameters like domain, company, limit, offset, and type.

  const DOMAIN_SEARCH_TOOL: Tool = {
    name: 'hunter_domain_search',
    description: 'Find all the email addresses corresponding to a website or company name.',
    inputSchema: {
      type: 'object',
      properties: {
        domain: {
          type: 'string',
          description: 'The domain name to search for, e.g. "stripe.com"',
        },
        company: {
          type: 'string',
          description: 'The company name to search for (alternative to domain)',
        },
        limit: {
          type: 'number',
          description: 'The maximum number of emails to return (default: 10, max: 100)',
        },
        offset: {
          type: 'number',
          description: 'The number of emails to skip (default: 0)',
        },
        type: {
          type: 'string',
          description: 'The type of emails to return (personal or generic)',
        }
      },
      required: [],
    },
  };

• src/index.ts:424-431 (registration)

  Registers the 'hunter_domain_search' tool (as DOMAIN_SEARCH_TOOL) in the list of tools returned by the ListToolsRequestSchema handler.

    tools: [
      FIND_EMAIL_TOOL,
      VERIFY_EMAIL_TOOL,
      DOMAIN_SEARCH_TOOL,
      EMAIL_COUNT_TOOL,
      ACCOUNT_INFO_TOOL,
    ],
  }));

• src/index.ts:138-144 (schema)

  TypeScript interface defining the input parameters for the 'hunter_domain_search' tool.

  interface DomainSearchParams {
    domain?: string;
    company?: string;
    limit?: number;
    offset?: number;
    type?: string;
  }

• src/index.ts:211-272 (helper)

  Type guard function that validates if the provided arguments match the DomainSearchParams interface, used in the handler for input validation.

  function isDomainSearchParams(args: unknown): args is DomainSearchParams {
    if (
      typeof args !== 'object' ||
      args === null
    ) {
      return false;
    }
  
    // At least one of domain or company must be provided
    if (
      !('domain' in args || 'company' in args)
    ) {
      return false;
    }
  
    // Check domain if provided
    if (
      'domain' in args &&
      (args as { domain: unknown }).domain !== undefined &&
      typeof (args as { domain: unknown }).domain !== 'string'
    ) {
      return false;
    }
  
    // Check company if provided
    if (
      'company' in args &&
      (args as { company: unknown }).company !== undefined &&
      typeof (args as { company: unknown }).company !== 'string'
    ) {
      return false;
    }
  
    // Check limit if provided
    if (
      'limit' in args &&
      (args as { limit: unknown }).limit !== undefined &&
      typeof (args as { limit: unknown }).limit !== 'number'
    ) {
      return false;
    }
  
    // Check offset if provided
    if (
      'offset' in args &&
      (args as { offset: unknown }).offset !== undefined &&
      typeof (args as { offset: unknown }).offset !== 'number'
    ) {
      return false;
    }
  
    // Check type if provided
    if (
      'type' in args &&
      (args as { type: unknown }).type !== undefined &&
      typeof (args as { type: unknown }).type !== 'string'
    ) {
      return false;
    }
  
    return true;
  }