Korea Tourism API MCP Server

Instructions

Implementation Reference

• src/mcp_tourism/server.py:150-281 (handler)

  The implementation of the search_tourism_by_keyword tool, which handles the logic for searching tourism information by keyword from the Korea Tourism Organization API.

  async def search_tourism_by_keyword(
      keyword: str,
      content_type: str | None = None,
      area_code: str | None = None,
      language: str | None = None,
      page: int = 1,
      rows: int = 20,
      filter: List[str] | None = None,
  ) -> dict:
      """
      Search for tourism information in Korea by keyword.
  
      This tool searches through the Korea Tourism Organization database for tourism items
      matching the specified keyword. It supports filtering by content type, area, and
      provides paginated results with detailed information.
  
      Args:
          keyword (str): Search keyword (e.g., "Gyeongbokgung", "Hanok", "Bibimbap")
          content_type (str, optional): Type of content to search for. Valid values:
              - "Tourist Attraction" (default)
              - "Cultural Facility"
              - "Festival Event"
              - "Leisure Activity"
              - "Accommodation"
              - "Shopping"
              - "Restaurant"
              - "Transportation"
          area_code (str, optional): Area code to filter results. Valid values:
              - "1" (Seoul)
              - "2" (Incheon)
              - "3" (Daejeon)
              - "4" (Daegu)
              - "5" (Gwangju)
              - "6" (Busan)
              - "7" (Ulsan)
              - "8" (Sejong)
              - "31" (Gyeonggi-do)
              - "32" (Gangwon-do)
              - "33" (Chungcheongbuk-do)
              - "34" (Chungcheongnam-do)
              - "35" (Gyeongsangbuk-do)
              - "36" (Gyeongsangnam-do)
              - "37" (Jeonbuk-do)
              - "38" (Jeollanam-do)
              - "39" (Jeju-do)
          language (str, optional): Language for results (default: "en"). Supported:
              - "en" (English)
              - "jp" (Japanese)
              - "zh-cn" (Simplified Chinese)
              - "zh-tw" (Traditional Chinese)
              - "de" (German)
              - "fr" (French)
              - "es" (Spanish)
              - "ru" (Russian)
          page (int, optional): Page number for pagination (default: 1, min: 1)
          rows (int, optional): Number of items per page (default: 20, max: 100)
          filter (list[str], optional): List of keys to include in each result item (whitelist).
              - If filter is None or an empty list ([]), all fields are returned.
              - If filter contains values, only the specified keys will be included in each item, and all other keys will be removed.
  
      Returns:
          dict: Search results with structure:
          {
              "total_count": int,     # Total number of matching items
              "num_of_rows": int,     # Number of items per page
              "page_no": int,         # Current page number
              "items": [              # List of tourism items
                  {
                      "title": str,           # Name of the attraction/place
                      "addr1": str,           # Primary address
                      "addr2": str,           # Secondary address
                      "areacode": str,        # Area code
                      "sigungucode": str,     # Sigungu code
                      "cat1": str,            # Category 1 code
                      "cat2": str,            # Category 2 code
                      "cat3": str,            # Category 3 code
                      "contentid": str,       # Unique content ID
                      "contenttypeid": str,   # Content type ID
                      "createdtime": str,     # Creation timestamp
                      "modifiedtime": str,    # Last modified timestamp
                      "tel": str,             # Phone number
                      "firstimage": str,      # URL of main image
                      "firstimage2": str,     # URL of thumbnail image
                      "mapx": str,            # Longitude
                      "mapy": str,            # Latitude
                      "mlevel": str,          # Map level
                      "cpyrhtDivCd": str      # Copyright division code
                  }
                  # ... more items
              ]
          }
  
      Example:
          search_tourism_by_keyword("Gyeongbokgung", "Tourist Attraction", "1", "en", 1, 10)
      """
      # Get the API client lazily
      client = get_api_client()
  
      # Validate and convert content_type
      content_type_id = None
      if content_type:
          content_type_id = next(
              (
                  k
                  for k, v in CONTENTTYPE_ID_MAP.items()
                  if v.lower() == content_type.lower()
              ),
              None,
          )
          if content_type_id is None:
              valid_types = ", ".join(CONTENTTYPE_ID_MAP.values())
              raise ValueError(
                  f"Invalid content_type: '{content_type}'. Valid types are: {valid_types}"
              )
  
      # Call the API client and return dict directly
      result = await client.search_by_keyword(
          keyword=keyword,
          content_type_id=content_type_id,
          area_code=area_code,
          language=language,
          page=page,
          rows=rows,
      )
      if filter:
          # Apply additional filtering if provided
          filter_items = []
          for item in result.get("items", []):
              item = {k: v for k, v in item.items() if k in filter}
              filter_items.append(item)
          result["items"] = filter_items
      return result

• src/mcp_tourism/server.py:149-150 (registration)

  The registration of the search_tourism_by_keyword tool using the @mcp.tool decorator.

  @mcp.tool
  async def search_tourism_by_keyword(