check_email

Instructions

Implementation Reference

• src/index.ts:211-281 (handler)

  The primary handler function that executes the check_email tool logic, querying the HIBP API for breached accounts associated with the given email and formatting the response.

  private async handleCheckEmail(args: any) {
    if (!args.email || typeof args.email !== "string") {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Email address is required"
      );
    }
  
    const params: Record<string, any> = {};
  
    if (args.include_unverified !== undefined) {
      params.includeUnverified = args.include_unverified;
    }
  
    if (args.truncate_response !== undefined) {
      params.truncateResponse = args.truncate_response;
    }
  
    const response = await this.axiosInstance.get(`/breachedaccount/${encodeURIComponent(args.email)}`, { params });
  
    if (!response.data || response.data.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: "Good news! This email address has not been found in any known data breaches.",
          },
        ],
      };
    }
  
    // Format the breach data for better readability
    const breaches = response.data;
    const breachCount = breaches.length;
  
    let summary = `⚠️ This email address was found in ${breachCount} data breach${breachCount > 1 ? 'es' : ''}.\n\n`;
  
    if (args.truncate_response) {
      // If truncated, just list the breach names
      summary += "Breaches: " + breaches.map((breach: any) => breach.Name).join(", ");
    } else {
      // Otherwise, provide detailed information
      summary += "Breach details:\n\n";
  
      breaches.forEach((breach: any, index: number) => {
        summary += `${index + 1}. ${breach.Name} (${breach.BreachDate})\n`;
        summary += `   Domain: ${breach.Domain}\n`;
        summary += `   Description: ${breach.Description}\n`;
        summary += `   Compromised data: ${breach.DataClasses.join(", ")}\n`;
  
        if (index < breaches.length - 1) {
          summary += "\n";
        }
      });
  
      summary += "\nRecommendations:\n";
      summary += "- Change your password for these services immediately\n";
      summary += "- If you used the same password elsewhere, change those too\n";
      summary += "- Enable two-factor authentication where available\n";
      summary += "- Consider using a password manager";
    }
  
    return {
      content: [
        {
          type: "text",
          text: summary,
        },
      ],
    };
  }

• src/index.ts:83-102 (schema)

  Input schema defining the parameters for the check_email tool, including email (required), include_unverified, and truncate_response options.

  inputSchema: {
    type: "object",
    properties: {
      email: {
        type: "string",
        description: "Email address to check",
      },
      include_unverified: {
        type: "boolean",
        description: "Include unverified breaches in the results",
        default: true,
      },
      truncate_response: {
        type: "boolean",
        description: "Truncate the response to only include breach names",
        default: false,
      },
    },
    required: ["email"],
  },

• src/index.ts:80-103 (registration)

  Registration of the check_email tool in the list of available tools returned by ListToolsRequestSchema.

  {
    name: "check_email",
    description: "Check if an email address has been found in data breaches",
    inputSchema: {
      type: "object",
      properties: {
        email: {
          type: "string",
          description: "Email address to check",
        },
        include_unverified: {
          type: "boolean",
          description: "Include unverified breaches in the results",
          default: true,
        },
        truncate_response: {
          type: "boolean",
          description: "Truncate the response to only include breach names",
          default: false,
        },
      },
      required: ["email"],
    },
  },

• src/index.ts:165-166 (handler)

  Dispatch in the CallToolRequestSchema handler that routes check_email calls to the handleCheckEmail function.

  case "check_email":
    return await this.handleCheckEmail(request.params.arguments);

• src/index.ts:182-191 (helper)

  Special error handling for 404 responses specific to check_email, treating it as a successful 'no breaches found' result.

  if (error.response?.status === 404 && request.params.name === "check_email") {
    return {
      content: [
        {
          type: "text",
          text: "Good news! This email address has not been found in any known data breaches.",
        },
      ],
    };
  }