mcp-helper-tools

Instructions

Implementation Reference

• src/tools/geo.ts:55-100 (handler)

  The main handler function for the 'geolocate' tool. It checks the cache first, enforces rate limiting, fetches geolocation data from ip-api.com if necessary, caches successful results, and returns a JSON-formatted 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:42-54 (schema)

  Tool metadata including name, description, and input schema definition for 'geolocate', specifying a required 'query' string parameter.

  geolocate: {
    name: 'geolocate',
    description: 'Get geolocation information for an IP address or domain',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'IP address or domain to lookup'
        }
      },
      required: ['query']
    },

• src/index.ts:27-33 (registration)

  Registration of the 'geolocate' tool by spreading geoTools into the central allTools registry used for listing and dispatching tool calls.

  const allTools: ToolKit = {
    ...encodingTools,
    ...geoTools,
    ...generatorTools,
    ...dateTimeTools,
    ...securityTools
  };

• src/tools/geo.ts:7-39 (helper)

  Helper function that constructs the API request to ip-api.com, fetches geolocation data, and extracts rate limit information from 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 }
    };
  }

• src/tools/geo.ts:4-5 (helper)

  Initialization of the geolocation-specific cache (5 minutes TTL) and rate limiter (45 req/min) used by the handler.

  const geoCache = new Cache<GeoLocation>(5 * 60 * 1000); // 5 minute cache
  const rateLimiter = new RateLimiter(45, 60000); // 45 requests per minute