OSINT MCP Server

Implementation Reference

• src/tools/hibp.ts:15-65 (handler)

  The 'checkBreaches' method in 'HibpApiClient' handles the logic of querying the HIBP API for email breaches.

  async checkBreaches(email: string): Promise<BreachResult[]> {
    const apiKey = configManager.get("HIBP_API_KEY");
    if (!apiKey) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        "HIBP_API_KEY is not configured"
      );
    }
  
    try {
      const data = await this.fetch<any[]>(`breachedaccount/${encodeURIComponent(email)}`, {
        method: "GET",
        headers: {
          "hibp-api-key": apiKey,
          "User-Agent": "OSINT-MCP-Server",
        },
      }, {
        truncateResponse: "false",
      });
  
      if (!data || data.length === 0) return [];
  
      return z.array(BreachResultSchema).parse(data.map((b: any) => ({
        name: b.Name,
        title: b.Title,
        domain: b.Domain,
        breachDate: b.BreachDate,
        addedDate: b.AddedDate,
        modifiedDate: b.ModifiedDate,
        pwnCount: b.PwnCount,
        description: b.Description,
        dataClasses: b.DataClasses,
        isVerified: b.IsVerified,
        isFabricated: b.IsFabricated,
        isSensitive: b.IsSensitive,
        isRetired: b.IsRetired,
        isSpamList: b.IsSpamList,
        logoPath: b.LogoPath,
      })));
    } catch (error: any) {
      if (error.message?.includes("404")) {
        // Not found means no breaches
        return [];
      }
      if (error instanceof McpError) throw error;
      throw new McpError(
        ErrorCode.InternalError,
        `HIBP error: ${(error as Error).message}`
      );
    }
  }

• src/index.ts:171-179 (registration)

  The 'check_breaches' tool is registered in 'src/index.ts' using the 'server.tool' method.

  server.tool(
    "check_breaches",
    { email: z.string().email().describe("Email address to check for breaches") },
    async ({ email }) => {
      const result = await hibpClient.checkBreaches(email);
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    }