IP Geolocation MCP Server

Instructions

Implementation Reference

• src/tools/astronomy.ts:210-262 (handler)

  Handler implementation for 'get_astronomy_time_series' which validates input, checks cache, calls the client function, and formats the response.

    async (params) => {
      try {
        const coordinateError = validateCoordinatePair(
          params.lat,
          params.long,
          "get_astronomy_time_series"
        );
        if (coordinateError) {
          throw new Error(coordinateError);
        }
  
        const dateRangeError = validateDateRange(
          params.dateStart,
          params.dateEnd,
          90
        );
        if (dateRangeError) {
          throw new Error(dateRangeError);
        }
  
        const elevationError = validateElevation(params.elevation, "elevation");
        if (elevationError) {
          throw new Error(elevationError);
        }
  
        const cacheKey = buildAstronomyTimeSeriesCacheKey(params);
        const cached = params.force_refresh ? undefined : getCachedValue(cacheKey);
        const result =
          cached ??
          (await getAstronomyTimeSeries({
            lat: params.lat,
            long: params.long,
            location: params.location,
            ip: params.ip,
            dateStart: params.dateStart,
            dateEnd: params.dateEnd,
            elevation: params.elevation,
            time_zone: params.time_zone,
            lang: params.lang,
          }));
        if (cached === undefined) {
          setCachedValue(cacheKey, result);
        }
        return {
          content: [
            { type: "text" as const, text: formatToolResult(result) },
          ],
        };
      } catch (error) {
        return errorToolResponse(error);
      }
    }
  );

• src/tools/astronomy.ts:143-208 (schema)

  MCP tool registration and schema definition for 'get_astronomy_time_series'.

    server.registerTool(
      "get_astronomy_time_series",
      {
        title: "Astronomy Time Series",
        annotations: {
          readOnlyHint: true,
        },
        description: `Daily astronomy time series via GET /v3/astronomy/timeSeries for up to 90 days. Works on free and paid plans. Cost: 1 credit per request.
  
  Returns location details plus an astronomy array with one daily entry per date. Use get_astronomy instead when you need real-time positional fields such as sun or moon altitude and azimuth.
  
  Location can be specified by coordinates, city/address, or IP. If no location is given, uses the caller's IP.`,
        inputSchema: {
          lat: z
            .string()
            .optional()
            .describe(
              "Latitude coordinate. Highest priority. Must be used with long."
            ),
          long: z
            .string()
            .optional()
            .describe("Longitude coordinate. Must be used with lat."),
          location: z
            .string()
            .optional()
            .describe("City or address string (e.g. San Francisco, CA)."),
          ip: z
            .string()
            .optional()
            .describe(
              "IPv4 or IPv6 address to get astronomy data for that IP's location."
            ),
          dateStart: z
            .string()
            .describe(
              "Start date in YYYY-MM-DD format. Required. Maximum range between dateStart and dateEnd is 90 days."
            ),
          dateEnd: z
            .string()
            .describe(
              "End date in YYYY-MM-DD format. Required. Maximum range between dateStart and dateEnd is 90 days."
            ),
          elevation: z
            .string()
            .optional()
            .describe(
              "Elevation in meters above sea level (0-10000). Affects sunrise/sunset calculations."
            ),
          time_zone: z
            .string()
            .optional()
            .describe(
              "IANA timezone name to express times in (e.g. America/New_York). If set, time fields include full date instead of just time."
            ),
          lang: z
            .string()
            .optional()
            .describe(
              "Response language for location fields in IP-based lookups (en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt). Paid plans only. Free plan returns 401 for non-English languages."
            ),
          force_refresh: z
            .boolean()
            .optional()
            .describe("Default false. Leave unset unless the user asks to refresh or rerun."),
        },