Fulcra Context MCP

Instructions

Implementation Reference

• fulcra_mcp/main.py:495-533 (handler)

  The handler function decorated with @mcp.tool(), implementing the core logic to fetch location time series data from FulcraAPI and return it as JSON string.

  @mcp.tool()
  async def get_location_time_series(
      start_time: datetime,
      end_time: datetime,
      change_meters: float | None = None,
      sample_rate: int | None = 900,
      reverse_geocode: bool | None = False,
  ) -> str:
      """Retrieve a time series of locations that the user was at.
      Result timestamps will include time zones. Always translate timestamps to the user's local tz when this is known.
  
      Args:
          start_time: The start of the time range (inclusive), as an ISO 8601 string or datetime object.
          end_time: The end of the range (exclusive), as an ISO 8601 string or datetime object.
          change_meters: Optional. When specified, subsequent samples that are fewer than this many meters away will not be included.
          sample_rate: Optional. The length (in seconds) of each sample. Default is 900.
          reverse_geocode: Optional. When true, Fulcra will attempt to reverse geocode the locations and include the details in the results. Default is False.
      Returns:
          A JSON string representing a list of location data points.
      """
      fulcra = get_fulcra_object()
      kwargs = {}
      if change_meters is not None:
          kwargs["change_meters"] = change_meters
      if sample_rate is not None:
          kwargs["sample_rate"] = sample_rate
      kwargs["look_back"] = 14400
      if reverse_geocode is not None:
          kwargs["reverse_geocode"] = reverse_geocode
  
      location_series = fulcra.location_time_series(
          start_time=start_time,
          end_time=end_time,
          **kwargs,
      )
      return f"Location time series from {start_time} to {end_time}: " + json.dumps(
          location_series
      )