Look up IP Address Privacy & Security

Instructions

Implementation Reference

• src/index.ts:200-234 (handler)

  The main handler function for the 'lookup_ip_address_privacy' tool. Validates the input IP address, fetches geolocation and privacy data from the IPLocate API, extracts the privacy and hosting fields, and returns the result as formatted JSON or an error response.

  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 privacyData = {
        ip: data.ip,
        privacy: data.privacy,
        hosting: data.hosting
      };
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify(privacyData, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error: ${error instanceof Error ? error.message : String(error)}`
        }],
        isError: true
      };
    }
  }

• src/index.ts:193-235 (registration)

  Registers the 'lookup_ip_address_privacy' tool with the MCP server, including its name, title, description, input schema reference, and inline handler function.

  server.registerTool(
    "lookup_ip_address_privacy",
    {
      title: "Look up IP Address Privacy & Security",
      description: "Check whether an IP address is detected as a VPN, proxy, other anonymizing service; is on an abuse blocklist; or is a hosting provider. 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 privacyData = {
          ip: data.ip,
          privacy: data.privacy,
          hosting: data.hosting
        };
  
        return {
          content: [{
            type: "text",
            text: JSON.stringify(privacyData, 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)

  Shared Zod input schema used by the lookup_ip_address_privacy tool (and other IP tools) defining an 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/models.ts:49-69 (schema)

  TypeScript interface defining the structure of the IPLocate API response, including 'privacy' and 'hosting' fields used by the tool handler.

  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;
  }

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

  Core helper function that performs the HTTP request to the IPLocate API to retrieve IP data, used by all IP lookup tools including lookup_ip_address_privacy.

  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)}`);
    }
  }