geolocate
Retrieve geolocation details for any IP address or domain quickly and accurately using the MCP Server’s dedicated tool. Ideal for network diagnostics and location verification.
Instructions
Get geolocation information for an IP address or domain
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | IP address or domain to lookup |
Input Schema (JSON Schema)
{
"properties": {
"query": {
"description": "IP address or domain to lookup",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
}
Implementation Reference
- src/tools/geo.ts:55-100 (handler)The handler function that implements the core logic of the geolocate tool: caching, rate limiting, API fetch, and response formatting.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 defining the required 'query' parameter (IP or domain) for the geolocate tool.inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'IP address or domain to lookup' } }, required: ['query'] },
- src/index.ts:28-35 (registration)Registers the geoTools (including geolocate) by spreading into the allTools object used for MCP tool listing and execution.const allTools: ToolKit = { ...systemTools, ...networkTools, ...geoTools, ...generatorTools, ...dateTimeTools, ...securityTools };
- src/index.ts:149-150 (registration)Specific rate limiter registration for the geolocate tool during tool execution handling.} else if (request.params.name === 'geolocate') { rateLimiter = geoRateLimiter;
- src/tools/geo.ts:7-39 (helper)Helper function to fetch geolocation data from the ip-api.com API and extract rate limit info.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 } }; }