Hunter.io MCP Server

Instructions

Implementation Reference

• src/index.ts:449-483 (handler)

  The handler logic for the 'hunter_find_email' tool, which validates input parameters using isFindEmailParams and calls the Hunter.io /email-finder API endpoint with retry logic.

  case 'hunter_find_email': {
    if (!isFindEmailParams(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid arguments for hunter_find_email'
      );
    }
  
    try {
      // Hunter.io API expects query parameters for email finder
      const response = await withRetry(
        async () => apiClient.get('/email-finder', { params: args }),
        'find email'
      );
  
      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:19-48 (schema)

  Input schema and metadata definition for the 'hunter_find_email' tool.

  const FIND_EMAIL_TOOL: Tool = {
    name: 'hunter_find_email',
    description: 'Find an email address using domain and name information.',
    inputSchema: {
      type: 'object',
      properties: {
        domain: {
          type: 'string',
          description: 'The domain name of the company, e.g. "stripe.com"',
        },
        first_name: {
          type: 'string',
          description: 'The first name of the person',
        },
        last_name: {
          type: 'string',
          description: 'The last name of the person',
        },
        company: {
          type: 'string',
          description: 'The name of the company',
        },
        full_name: {
          type: 'string',
          description: 'The full name of the person (alternative to first_name and last_name)',
        }
      },
      required: ['domain'],
    },
  };

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

  Registration of the 'hunter_find_email' tool (via FIND_EMAIL_TOOL) in the ListTools request handler.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      FIND_EMAIL_TOOL,
      VERIFY_EMAIL_TOOL,
      DOMAIN_SEARCH_TOOL,
      EMAIL_COUNT_TOOL,
      ACCOUNT_INFO_TOOL,
    ],
  }));

• src/index.ts:156-200 (helper)

  Type guard helper function to validate arguments for the 'hunter_find_email' tool.

  function isFindEmailParams(args: unknown): args is FindEmailParams {
    if (
      typeof args !== 'object' ||
      args === null ||
      !('domain' in args) ||
      typeof (args as { domain: unknown }).domain !== 'string'
    ) {
      return false;
    }
  
    // Optional parameters
    if (
      'first_name' in args &&
      (args as { first_name: unknown }).first_name !== undefined &&
      typeof (args as { first_name: unknown }).first_name !== 'string'
    ) {
      return false;
    }
  
    if (
      'last_name' in args &&
      (args as { last_name: unknown }).last_name !== undefined &&
      typeof (args as { last_name: unknown }).last_name !== 'string'
    ) {
      return false;
    }
  
    if (
      'company' in args &&
      (args as { company: unknown }).company !== undefined &&
      typeof (args as { company: unknown }).company !== 'string'
    ) {
      return false;
    }
  
    if (
      'full_name' in args &&
      (args as { full_name: unknown }).full_name !== undefined &&
      typeof (args as { full_name: unknown }).full_name !== 'string'
    ) {
      return false;
    }
  
    return true;
  }

• src/index.ts:126-132 (helper)

  TypeScript interface definition for parameters used by the 'hunter_find_email' tool.

  interface FindEmailParams {
    domain: string;
    first_name?: string;
    last_name?: string;
    company?: string;
    full_name?: string;
  }