IPLocate

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