osint-mcp-server

Instructions

Implementation Reference

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

  The actual implementation of the geoip_lookup tool which fetches data from ip-api.com.

  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/protocol/tools.ts:321-328 (registration)

  Tool definition and registration for geoip_lookup.

  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/geoip/index.ts:7-26 (schema)

  Type definition for the GeoIP lookup result.

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