Look up IP Address Details

Instructions

Implementation Reference

• src/index.ts:99-133 (handler)

  The handler function that implements the core logic of the lookup_ip_address_details tool: IP validation, API call, disclaimer addition, and response formatting.

  async ({ ip }) => {
    if (ip && !isValidIP(ip)) {
      return {
        content: [{
          type: "text",
          text: `Error: "${ip}" is not a valid IPv4 or IPv6 address.`
        }],
        isError: true
      };
    }
  
    try {
      const data = await fetchIPData(ip);
  
      const dataWithDisclaimer = {
        ...data,
        disclaimer: DISCLAIMER
      };
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify(dataWithDisclaimer, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error: ${error instanceof Error ? error.message : String(error)}`
        }],
        isError: true
      };
    }
  }

• src/index.ts:14-16 (schema)

  Input schema for the tool defining the optional 'ip' parameter.

  const IPAddressSchema = {
    ip: z.string().optional().describe("IPv4 or IPv6 address to look up. If not provided, returns information about the caller's IP address.")
  };

• src/index.ts:92-134 (registration)

  Registration of the lookup_ip_address_details tool with the MCP server, specifying name, metadata, input schema, and handler.

  server.registerTool(
    "lookup_ip_address_details",
    {
      title: "Look up IP Address Details",
      description: "Get comprehensive information about an IP address including geolocation, network details, privacy/security information, company data, and abuse contacts. Can look up any IPv4 or IPv6 address, or your own IP if no address is provided.",
      inputSchema: IPAddressSchema
    },
    async ({ ip }) => {
      if (ip && !isValidIP(ip)) {
        return {
          content: [{
            type: "text",
            text: `Error: "${ip}" is not a valid IPv4 or IPv6 address.`
          }],
          isError: true
        };
      }
  
      try {
        const data = await fetchIPData(ip);
  
        const dataWithDisclaimer = {
          ...data,
          disclaimer: DISCLAIMER
        };
  
        return {
          content: [{
            type: "text",
            text: JSON.stringify(dataWithDisclaimer, null, 2)
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: `Error: ${error instanceof Error ? error.message : String(error)}`
          }],
          isError: true
        };
      }
    }
  );

• src/index.ts:44-89 (helper)

  Helper function that performs the actual API request to iplocate.io to retrieve IP address details.

  async function fetchIPData(ip?: string): Promise<IPLocateResponse> {
    const baseUrl = "https://iplocate.io/api/lookup";
    const apiKey = process.env.IPLOCATE_API_KEY;
  
    let url = ip ? `${baseUrl}/${ip}` : `${baseUrl}/`;
  
    // Add API key if available
    if (apiKey) {
      url += `?apikey=${apiKey}`;
    }
  
    try {
      const response = await fetch(url, {
        headers: {
          'User-Agent': `mcp-server-iplocate/${VERSION}`
        }
      });
  
      if (!response.ok) {
        const errorText = await response.text();
        let errorMessage = `API request failed with status ${response.status}`;
  
        try {
          const errorJson = JSON.parse(errorText);
          if (errorJson.error) {
            errorMessage = errorJson.error;
          }
        } catch {
          // If not JSON, use the raw text
          if (errorText) {
            errorMessage = errorText;
          }
        }
  
        throw new Error(errorMessage);
      }
  
      const data = await response.json() as IPLocateResponse;
      return data;
    } catch (error) {
      if (error instanceof Error) {
        throw error;
      }
      throw new Error(`Failed to fetch IP data: ${String(error)}`);
    }
  }

• src/index.ts:25-41 (helper)

  Helper function to validate if a given string is a valid IPv4 or IPv6 address.

  function isValidIP(ip: string): boolean {
    // IPv4 pattern
    const ipv4Pattern = /^(\d{1,3}\.){3}\d{1,3}$/;
    // IPv6 pattern (simplified)
    const ipv6Pattern = /^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$/;
  
    if (ipv4Pattern.test(ip)) {
      // Validate IPv4 octets
      const octets = ip.split('.');
      return octets.every(octet => {
        const num = parseInt(octet, 10);
        return num >= 0 && num <= 255;
      });
    }
  
    return ipv6Pattern.test(ip);
  }

• src/models.ts:49-69 (schema)

  TypeScript interface defining the structure of the IP location response data used by the tool.

  export interface IPLocateResponse {
    ip: string;
    country?: string | null;
    country_code?: string | null;
    is_eu?: boolean;
    city?: string | null;
    continent?: string | null;
    latitude?: number | null;
    longitude?: number | null;
    time_zone?: string | null;
    postal_code?: string | null;
    subdivision?: string | null;
    currency_code?: string | null;
    calling_code?: string | null;
    network?: string | null;
    asn?: ASNInfo | null;
    privacy?: PrivacyInfo;
    company?: CompanyInfo | null;
    hosting?: HostingInfo | null;
    abuse?: AbuseInfo | null;
  }