Edinburgh Festivals MCP Server

Instructions

Implementation Reference

• main.py:78-131 (handler)

  The edinburgh_festival_events tool handler function. Decorated with @mcp.tool() for registration. Processes parameters for date range, festival, genre, etc., calls edfestcli.EdFestCli().events() to retrieve events from the Edinburgh Festival API, and returns the list of events.

  @mcp.tool()
  def edinburgh_festival_events(
      datetime_from="2025-01-01 00:00:00",
      datetime_to="2025-12-31 23:59:59",
      festival="international",
      genre=None,
      venue_name=None,
      search_text=None,
      title=None,
      artist=None,
      number_of_results=25,
      page=0,
      year="*",
  ) -> List[Dict]:
      """
      Searches this year's Edinburgh festival events.
      :param datetime_from: An optional ISO8601-like timestamp. e.g. '2025-08-12 00:00:00'
      :param datetime_to:  An optional ISO8601-like timestamp. e.g. '2025-08-12 00:00:00'
      :param festival:  possible values are fringe, demofringe, jazz, book, international, tattoo, art, hogmanay, science, imaginate, film, mela, storytelling.
      :param genre: The genre of the show. This will vary by festival type but may include comedy, theatre etc
      :param venue_name: The genre of the show. This will vary by festival type but may include comedy, theatre etc
      :param search_text:  description  of the show to search for.
      :param artist:  Name of an artist or performer to search for.
      :param title: the title of the show to search for.
      :param year: The year of the festival. Defaults to "*", which means all years.
      :param datetime_from: The start date and time for the search range.
      :param number_of_results: The maximum number of results to retrieve, up to 100 at a time.
      :param page: The page number for pagination, starting from 0.
      :return:
      """
      params = {
          "festival": festival,
          "year": year,
          "date_from": datetime_from.replace("T", " "),
          "date_to": datetime_to.replace("T", " "),
          "genre": genre,
          "venue_name": venue_name,
          "description": search_text,
          "artist": artist,
          "title": title,
          "size": number_of_results,
          "page": page,
      }
      ## If year is "*", we remove the date filters
      if year == "*":
          del params["date_from"]
          del params["date_to"]
      filtered_params = {k: v for k, v in params.items() if v}
  
      results = cli.events(filtered_params)
      # for r in results:
      #     del r['images']
      return results

• edfestcli.py:22-26 (helper)

  The events() method in EdFestCli class, which is invoked by the tool handler. Adjusts festival param if needed and calls _send_request to fetch events from the API.

  def events(self, params: Dict) -> List[Dict]:
      if params.get("festival") == "fringe" and self._fringe_mode != "real":
          params["festival"] = "demofringe"
      return self._send_request("events", params)

• edfestcli.py:30-48 (helper)

  The _send_request() private method used by events() to sign the API request with HMAC-SHA1 and make HTTP GET to edinburghfestivalcity.com API.

  def _send_request(self, path: str, params: Dict) -> Dict:
      params["key"] = self._apikey
      query = urlencode(params)
      url_to_sign = f"/{path}?{query}"
      signature = hmac.new(
          self._apisecret.encode("utf-8"), url_to_sign.encode("utf-8"), hashlib.sha1
      ).hexdigest()
      signed_url = f"{url_to_sign}&signature={signature}"
      url_to_request = f"{EdFestCli.base_url}{signed_url}"
      original_stderr = sys.stderr  # Save the original stderr
      with open("error.log", "a") as f:
          sys.stderr = f  # Redirect stderr to the file
  
          # Any stderr output now goes to 'error.log'
          print(url_to_request, file=sys.stderr)
      sys.stderr = original_stderr  # Restore the original stderr
      response = requests.get(url_to_request)
      return response.json()

• edfestcli.py:16-21 (helper)

  The __init__ method of EdFestCli, loads API credentials from env vars.

  def __init__(self):
      load_dotenv()
      self._apikey = os.getenv("api_key")
      self._apisecret = os.getenv("api_secret")
      self._fringe_mode = os.getenv("fringe_mode", "demo")

• main.py:10-11 (helper)

  Instantiation of the EdFestCli() as 'cli' global, used by the tool.

  cli = edfestcli.EdFestCli()
  gmaps_cli = gmaps.GMAPS()