geoip_lookup

Instructions

Implementation Reference

• src/geoip/index.ts:30-38 (handler)

  Core handler function that performs a single IP geolocation lookup via ip-api.com free API. Accepts an IP string, applies rate limiting, fetches from http://ip-api.com/json/, and returns a GeoIpResult with country, city, ISP, ASN, proxy/hosting/mobile flags.

  export async function geoipLookup(ip: string): Promise<GeoIpResult> {
    await limiter.acquire();
    // ip-api.com free tier requires HTTP (not HTTPS)
    const res = await fetch(`http://ip-api.com/json/${encodeURIComponent(ip)}?fields=status,message,query,country,countryCode,region,regionName,city,zip,lat,lon,timezone,isp,org,as,asname,mobile,proxy,hosting`);
    if (!res.ok) throw new Error(`ip-api.com returned ${res.status}`);
    const data = await res.json();
    if (data.status === "fail") throw new Error(`ip-api.com: ${data.message}`);
    return data;
  }

• src/geoip/index.ts:7-26 (schema)

  GeoIpResult interface defining the response shape: query, status, country, countryCode, region, city, lat/lon, timezone, ISP, org, ASN, and boolean flags for mobile/proxy/hosting.

  interface GeoIpResult {
    query: string;
    status: string;
    country?: string;
    countryCode?: string;
    region?: string;
    regionName?: string;
    city?: string;
    zip?: string;
    lat?: number;
    lon?: number;
    timezone?: string;
    isp?: string;
    org?: string;
    as?: string;
    asname?: string;
    mobile?: boolean;
    proxy?: boolean;
    hosting?: boolean;
  }

• src/protocol/tools.ts:321-328 (registration)

  Tool definition/registration for 'geoip_lookup'. Defines name, description, Zod schema (ip: string), and execute handler that calls geoipLookup().

  const geoipLookupTool: ToolDef = {
    name: "geoip_lookup",
    description: "Geolocate an IP address: country, city, ISP, ASN, proxy/hosting/mobile detection. Uses ip-api.com (free, no API key).",
    schema: {
      ip: z.string().describe("IP address to geolocate"),
    },
    execute: async (args) => json(await geoipLookup(args.ip as string)),
  };

• src/protocol/tools.ts:512-514 (registration)

  Registration of geoipLookupTool in the exported allTools array that collects all tool definitions for the MCP server.

  // GeoIP (2)
  geoipLookupTool,
  geoipBatchTool,

• src/utils/rate-limiter.ts:1-34 (helper)

  RateLimiter class used by geoipLookup to ensure minimum delay (1400ms = ~45 req/min) between requests to ip-api.com free tier.

  // Queue-based rate limiter — ensures minimum delay between requests
  export class RateLimiter {
    private lastRequest = 0;
    private queue: (() => void)[] = [];
    private processing = false;
  
    constructor(private minDelayMs: number) {}
  
    async acquire(): Promise<void> {
      return new Promise<void>((resolve) => {
        this.queue.push(resolve);
        if (!this.processing) this.processQueue();
      });
    }
  
    private async processQueue(): Promise<void> {
      this.processing = true;
      while (this.queue.length > 0) {
        const now = Date.now();
        const elapsed = now - this.lastRequest;
        if (elapsed < this.minDelayMs) {
          await sleep(this.minDelayMs - elapsed);
        }
        this.lastRequest = Date.now();
        const resolve = this.queue.shift();
        resolve?.();
      }
      this.processing = false;
    }
  }
  
  function sleep(ms: number): Promise<void> {
    return new Promise((r) => setTimeout(r, ms));
  }