Find Business Email

Instructions

Implementation Reference

• deliveriq-mcp/src/tools/intelligence.ts:13-97 (handler)

  The registerIntelligenceTools function registers the 'deliveriq_find_email' tool with the MCP server. The handler (lines 45-95) calls client.emailFinder.find() with name and domain params, then formats a detailed response including email, confidence score, verification method, domain context, and corroboration signals.

  export function registerIntelligenceTools(server: McpServer, client: DeliverIQ): void {
    // ── 6. deliveriq_find_email ───────────────────────────────────
  
    server.registerTool(
      'deliveriq_find_email',
      {
        title: 'Find Business Email',
        description: `Find a person's business email address by name and company domain. Uses pattern generation, SMTP probing, corroboration from public sources, and org intelligence.
  
  Args:
    - first_name (string): Person's first name
    - last_name (string): Person's last name
    - domain (string, optional): Company domain (e.g. "acme.com"). Required if company_name is not set
    - middle_name (string, optional): Middle name for disambiguation
    - company_name (string, optional): Company name, used to resolve domain if domain is not provided
  
  Returns:
    Found email address, confidence score and label, verification method, and domain context.
  
  Examples:
    - "Find John Doe at acme.com" -> { first_name: "John", last_name: "Doe", domain: "acme.com" }
    - "Find Jane Smith at Globex Corp" -> { first_name: "Jane", last_name: "Smith", company_name: "Globex Corp" }
  
  Credit cost: 2 credits per lookup`,
        inputSchema: FindEmailSchema,
        annotations: {
          readOnlyHint: false,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
        },
      },
      async (params) => {
        try {
          const res = await client.emailFinder.find({
            firstName: params.first_name,
            lastName: params.last_name,
            domain: params.domain,
            middleName: params.middle_name,
            companyName: params.company_name,
          });
  
          const r = res.result;
          const lines = [
            `# Email Finder: ${res.firstName} ${res.lastName} @ ${res.domain}`,
            '',
          ];
  
          if (r.email) {
            lines.push(
              `**Email**: ${r.email}`,
              `**Confidence**: ${r.confidence}% (${r.confidenceLabel})`,
              `**Method**: ${r.verificationMethod.replace(/_/g, ' ')}`,
            );
            if (r.pattern) lines.push(`**Pattern**: ${r.pattern}`);
          } else {
            lines.push('**Result**: No email found.');
            if (r.probeDetails?.failureReason) {
              lines.push(`**Reason**: ${r.probeDetails.failureReason}`);
            }
          }
  
          lines.push(
            '',
            '## Domain Context',
            `- MX Provider: ${r.domainContext.mxProvider ?? 'Unknown'}`,
            `- Catch-all: ${r.domainContext.isCatchAll ? 'Yes' : 'No'}`,
            `- Infrastructure Score: ${r.domainContext.infrastructureScore ?? 'N/A'}`,
          );
  
          if (r.corroboration && r.corroboration.signals.length > 0) {
            lines.push('', '## Corroboration');
            for (const sig of r.corroboration.signals) {
              lines.push(`- ${sig.source}: ${sig.found ? 'Found' : 'Not found'}${sig.matchedEmail ? ` (${sig.matchedEmail})` : ''}`);
            }
          }
  
          lines.push('', `*Completed in ${r.durationMs}ms*`);
          return successResponse(lines.join('\n'));
        } catch (error) {
          return handleSdkError(error);
        }
      },
    );

• deliveriq-mcp/src/schemas/intelligence.ts:1-14 (schema)

  Zod schema defining input validation for deliveriq_find_email: first_name (required string), last_name (required string), domain (optional string), middle_name (optional string), company_name (optional string). The schema is strict (no extra properties allowed).

  import { z } from 'zod';
  
  export const FindEmailSchema = z.object({
    first_name: z.string().min(1)
      .describe('First name of the person (e.g. "John")'),
    last_name: z.string().min(1)
      .describe('Last name of the person (e.g. "Doe")'),
    domain: z.string().optional()
      .describe('Company domain (e.g. "acme.com"). Required if company_name is not provided'),
    middle_name: z.string().optional()
      .describe('Middle name (improves accuracy for common names)'),
    company_name: z.string().optional()
      .describe('Company name (e.g. "Acme Corp"). Used if domain is not provided'),
  }).strict();

• deliveriq-mcp/src/tools/intelligence.ts:16-44 (registration)

  The tool is registered via server.registerTool('deliveriq_find_email', ...) with title 'Find Business Email', description with usage instructions, inputSchema set to FindEmailSchema, and annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).

    server.registerTool(
      'deliveriq_find_email',
      {
        title: 'Find Business Email',
        description: `Find a person's business email address by name and company domain. Uses pattern generation, SMTP probing, corroboration from public sources, and org intelligence.
  
  Args:
    - first_name (string): Person's first name
    - last_name (string): Person's last name
    - domain (string, optional): Company domain (e.g. "acme.com"). Required if company_name is not set
    - middle_name (string, optional): Middle name for disambiguation
    - company_name (string, optional): Company name, used to resolve domain if domain is not provided
  
  Returns:
    Found email address, confidence score and label, verification method, and domain context.
  
  Examples:
    - "Find John Doe at acme.com" -> { first_name: "John", last_name: "Doe", domain: "acme.com" }
    - "Find Jane Smith at Globex Corp" -> { first_name: "Jane", last_name: "Smith", company_name: "Globex Corp" }
  
  Credit cost: 2 credits per lookup`,
        inputSchema: FindEmailSchema,
        annotations: {
          readOnlyHint: false,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
        },
      },

• deliveriq-mcp/src/constants.ts:5-18 (helper)

  Constant CREDIT_COSTS defines the credit cost for deliveriq_find_email as 2 credits per lookup.

  export const CREDIT_COSTS: Record<string, number | string> = {
    deliveriq_verify_email: 1,
    deliveriq_batch_verify: '1 per email',
    deliveriq_batch_status: 0,
    deliveriq_batch_download: 0,
    deliveriq_list_jobs: 0,
    deliveriq_find_email: 2,
    deliveriq_blacklist_check: 1,
    deliveriq_infrastructure_check: 1,
    deliveriq_spam_trap_analysis: 1,
    deliveriq_domain_intel: 1,
    deliveriq_org_intel: 0,
    deliveriq_check_credits: 0,
  };