geolocate
Find geographic location details for IP addresses or domains to identify origin and network information.
Instructions
Get geolocation information for an IP address or domain
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | IP address or domain to lookup |
Implementation Reference
- src/tools/geo.ts:55-100 (handler)The handler function for the 'geolocate' tool. It checks cache, enforces rate limiting, fetches geolocation data from ip-api.com, caches successful results, and returns formatted JSON response.
handler: async ({ query }: { query: string }) => { // Check cache first const cached = geoCache.get(query); if (cached) { return { content: [{ type: 'text', text: JSON.stringify({ data: cached, source: 'cache' }, null, 2) }] }; } // Check rate limit if (!rateLimiter.canMakeRequest()) { const timeToReset = rateLimiter.getTimeToReset(); throw new Error(`Rate limit exceeded. Please try again in ${Math.ceil(timeToReset / 1000)} seconds.`); } try { const { data, rateLimit } = await fetchGeoData(query); // Update rate limiter based on response headers rateLimiter.incrementRequests(); // Cache successful responses if (data.status === 'success') { geoCache.set(query, data); } return { content: [{ type: 'text', text: JSON.stringify({ data, rateLimit, source: 'api' }, null, 2) }] }; } catch (error) { throw new Error(`Geolocation failed: ${error instanceof Error ? error.message : 'Unknown error'}`); } } - src/tools/geo.ts:45-54 (schema)Input schema definition for the 'geolocate' tool, requiring a 'query' parameter (IP or domain).
inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'IP address or domain to lookup' } }, required: ['query'] }, - src/index.ts:28-35 (registration)Registration of all tools including geoTools (which contains 'geolocate') into the allTools object used for tool listing and execution.
const allTools: ToolKit = { ...systemTools, ...networkTools, ...geoTools, ...generatorTools, ...dateTimeTools, ...securityTools }; - src/index.ts:149-150 (registration)Specific rate limiter selection for the 'geolocate' tool during tool execution dispatch.
} else if (request.params.name === 'geolocate') { rateLimiter = geoRateLimiter; - src/tools/geo.ts:7-39 (helper)Helper function to fetch geolocation data from ip-api.com API, including rate limit headers.
async function fetchGeoData(query: string): Promise<{ data: GeoLocation; rateLimit: RateLimitInfo }> { const fields = [ 'status', 'message', 'country', 'countryCode', 'region', 'regionName', 'city', 'zip', 'lat', 'lon', 'timezone', 'offset', 'isp', 'org', 'as', 'query' ].join(','); const url = `http://ip-api.com/json/${encodeURIComponent(query)}?fields=${fields}`; const response = await fetch(url); const data = await response.json() as GeoLocation; const remaining = Number(response.headers.get('X-Rl') ?? '0'); const ttl = Number(response.headers.get('X-Ttl') ?? '0'); return { data, rateLimit: { remaining, ttl } }; }