IPLocate

Instructions

Implementation Reference

• src/index.ts:144-189 (handler)

  The handler function that implements the core logic of the 'lookup_ip_address_location' tool. Validates IP, fetches data, filters to location fields, adds disclaimer, handles errors, and returns JSON-formatted 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 locationData = {
        ip: data.ip,
        country: data.country,
        country_code: data.country_code,
        is_eu: data.is_eu,
        city: data.city,
        continent: data.continent,
        latitude: data.latitude,
        longitude: data.longitude,
        time_zone: data.time_zone,
        postal_code: data.postal_code,
        subdivision: data.subdivision,
        currency_code: data.currency_code,
        calling_code: data.calling_code,
        disclaimer: DISCLAIMER
      };
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify(locationData, 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)

  Zod-based input schema defining the optional 'ip' parameter for the tool.

  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:136-190 (registration)

  Tool registration call using McpServer.registerTool, specifying name, title, description, input schema, and inline handler function.

  // Register tool: lookup_ip_address_location
  server.registerTool(
    "lookup_ip_address_location",
    {
      title: "Look up IP Address Location",
      description: "Get geographic location information for an IP address including country, city, coordinates, timezone, and postal code. 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 locationData = {
          ip: data.ip,
          country: data.country,
          country_code: data.country_code,
          is_eu: data.is_eu,
          city: data.city,
          continent: data.continent,
          latitude: data.latitude,
          longitude: data.longitude,
          time_zone: data.time_zone,
          postal_code: data.postal_code,
          subdivision: data.subdivision,
          currency_code: data.currency_code,
          calling_code: data.calling_code,
          disclaimer: DISCLAIMER
        };
  
        return {
          content: [{
            type: "text",
            text: JSON.stringify(locationData, null, 2)
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: `Error: ${error instanceof Error ? error.message : String(error)}`
          }],
          isError: true
        };
      }
    }
  );

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

  TypeScript interface defining the full structure of the IP geolocation API response data, imported and used to type the fetchIPData return value and extract location fields.

  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)

  Helper function that performs the actual HTTP fetch to the iplocate.io API, constructs URL with optional IP and API key, handles HTTP errors and JSON parsing, returns typed response data. Central to all IP lookup tools.

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