fetch_bop_data

Instructions

Retrieves compact format time series data from the BOP database based on the input parameters.

Args:
    freq (str): Frequency (e.g., "A" for annual, "Q" for quarterly, "M" for monthly).
    country (str): Country code, multiple country codes can be connected with "+".
    indicator (str): Indicator code.
    start (str | int): Start year.
    end (str | int): End year.

Returns:
    str: Description of the queried data. Do not perform further analysis or retry if the query fails.

Implementation Reference

• imf_data_mcp/__init__.py:122-146 (handler)

  The main handler function for the 'fetch_bop_data' tool. It is registered via the @mcp.tool() decorator and implements the logic to fetch Balance of Payments (BOP) time series data from the IMF API, process it using process_imf_data, or return an error.

  @mcp.tool()
  def fetch_bop_data(freq: str, country: str, indicator: str, start: str | int, end: str | int) -> str:
      """
      Retrieves compact format time series data from the BOP database based on the input parameters.
  
      Args:
          freq (str): Frequency (e.g., "A" for annual, "Q" for quarterly, "M" for monthly).
          country (str): Country code, multiple country codes can be connected with "+".
          indicator (str): Indicator code.
          start (str | int): Start year.
          end (str | int): End year.
  
      Returns:
          str: Description of the queried data. Do not perform further analysis or retry if the query fails.
      """
      dimensions = f"{freq}.{country}.{indicator}"
      url = f"http://dataservices.imf.org/REST/SDMX_JSON.svc/CompactData/BOP/{dimensions}?startPeriod={start}&endPeriod={end}"
      try:
          response = requests.get(url)
          response.raise_for_status()
          data = response.json()
  
          return process_imf_data(data)
      except Exception as e:
          return f"Error fetching BOP data: {str(e)}"

• imf_data_mcp/utils.py:1-52 (helper)

  Helper utility function imported and used by fetch_bop_data (and other tools) to parse the IMF JSON response into a human-readable string summary of the time series data.

  def process_imf_data(json_data: dict) -> str:
      """
      Process IMF data and return a string with the information.
      :param:
          json_data(dict): JSON data from the IMF API
      :return:
          (str) A string with the information from the JSON data
      """
      try:
         
          json_data = json_data["CompactData"]
          dataset = json_data["DataSet"]
  
          series_list = dataset["Series"]
          if isinstance(series_list, dict):
              series_list = [series_list]
          elif not isinstance(series_list, list):
              return f"Error: Expected series_list to be a list but got {type(series_list)}"
  
          output_texts = []
          
          for series in series_list:
              if series is None:
                  output_texts.append("Warning: No indicator value.")
                  continue
              country = series.get("@REF_AREA", None)
              obs = series.get("Obs", {})
              if isinstance(obs, dict):
                  obs = [obs]
              elif not isinstance(obs, list):
                  return f"Error: Expected obs to be a list but got {type(obs)}"
              for _obs in obs:
                  if _obs is None:
                      output_texts.append(
                          f"Warning: No indicator value for {country} in that Year, You should not try to access the data of this country."
                      )
                      continue
                  time_period = _obs.get("@TIME_PERIOD", "that Year")
                  obs_value = _obs.get("@OBS_VALUE")
                  
                  if obs_value is not None:
                      text = f"In {time_period}, {country} had an indicator value of {float(obs_value):.2f}."
                      output_texts.append(text)
                  else:
                      output_texts.append(f"Warning: No indicator value for {country} in {time_period}.")
          
          return "\n".join(output_texts)
      except KeyError as e:
          return f"Error processing IMF data: Missing key {str(e)}"
      except Exception as e:
          return f"Error processing IMF data: {str(e)}"

• imf_data_mcp/__init__.py:122-122 (registration)

  The @mcp.tool() decorator registers the fetch_bop_data function as an MCP tool, using the function name as the tool name.

  @mcp.tool()