IPLocate

Instructions

Implementation Reference

• src/index.ts:245-279 (handler)

  The handler function for the 'lookup_ip_address_network' tool. It validates the optional IP input, fetches IP data using the shared fetchIPData helper, extracts network-related fields (ip, network, asn), and returns a JSON-formatted text response or error.

  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 networkData = {
        ip: data.ip,
        network: data.network,
        asn: data.asn
      };
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify(networkData, 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 definition used by the tool for validating 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:238-280 (registration)

  Registration of the 'lookup_ip_address_network' tool on the MCP server, including name, metadata (title, description), input schema reference, and inline handler function.

  server.registerTool(
    "lookup_ip_address_network",
    {
      title: "Look up IP Address Network (ASN)",
      description: "Get network and ASN (Autonomous System Number) information for an IP address including the network operator, route, and regional registry. 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 networkData = {
          ip: data.ip,
          network: data.network,
          asn: data.asn
        };
  
        return {
          content: [{
            type: "text",
            text: JSON.stringify(networkData, 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)

  Shared helper function to fetch IP geolocation data from the iplocate.io API, used by all IP lookup tools including this one.

  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/models.ts:49-69 (schema)

  TypeScript interface defining the structure of the IPLocate API response, which includes the 'network' and 'asn' fields extracted by this tool's 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;
  }