Korea Tourism API MCP Server

Instructions

Implementation Reference

• src/mcp_tourism/server.py:651-751 (handler)

  The implementation of the 'find_accommodations' tool handler, which utilizes the KoreaTourismApiClient to fetch data and applies an optional filter to the results.

  async def find_accommodations(
      area_code: str | None = None,
      sigungu_code: str | None = None,
      language: str | None = None,
      page: int = 1,
      rows: int = 20,
      filter: list[str] | None = None,
  ) -> dict:
      """
      Find accommodations in Korea by area.
  
      This tool searches for accommodation options (hotels, guesthouses, pensions, etc.)
      in a specific area in Korea. It provides detailed information about lodging
      facilities including location, contact information, and special certifications.
  
      Args:
          area_code (str, optional): Area code. 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)
          sigungu_code (str, optional): Sigungu (district) code within the area
          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: Accommodation options 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 accommodation items
                  {
                      "title": str,           # Name of the accommodation
                      "addr1": str,           # Primary address
                      "addr2": str,           # Secondary address
                      "areacode": str,        # Area code
                      "sigungucode": str,     # Sigungu code
                      "contentid": str,       # Unique content ID
                      "contenttypeid": str,   # Content type ID
                      "createdtime": str,     # Creation timestamp
                      "firstimage": str,      # URL of main image
                      "firstimage2": str,     # URL of thumbnail image
                      "mapx": str,            # Longitude
                      "mapy": str,            # Latitude
                      "mlevel": str,          # Map level
                      "tel": str,             # Phone number
                      "cat1": str,            # Category 1 code
                      "cat2": str,            # Category 2 code
                      "cat3": str,            # Category 3 code
                      "hanok": str,           # Korean traditional house flag
                      "benikia": str,         # Benikia hotel flag
                      "goodstay": str         # Goodstay accommodation flag
                  }
                  # ... more items
              ]
          }
  
      Example:
          find_accommodations("1", "1", "en", 1, 20)
      """
      # Call the API client and return dict directly
      result = await get_api_client().search_stay(
          area_code=area_code,
          sigungu_code=sigungu_code,
          language=language,
          page=page,
          rows=rows,
      )
      if filter:
          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:650-650 (registration)

  Registration of the find_accommodations function as an MCP tool using the @mcp.tool decorator.

  @mcp.tool