Korea Tourism API MCP Server

Instructions

Implementation Reference

• src/mcp_tourism/server.py:417-533 (handler)

  The 'find_nearby_attractions' tool implementation, which validates input parameters and calls the API client to fetch location-based tourism data.

  async def find_nearby_attractions(
      longitude: float,
      latitude: float,
      radius: int = 1000,
      content_type: str | None = None,
      language: str | None = None,
      page: int = 1,
      rows: int = 20,
      filter: list[str] | None = None,
  ) -> dict:
      """
      Find tourism attractions near a specific location in Korea.
  
      This tool performs a location-based search to find tourism items within a specified
      radius of given GPS coordinates. It's useful for finding nearby attractions,
      restaurants, or other tourism facilities when you know a specific location.
  
      Args:
          longitude (float): Longitude coordinate (e.g., 126.9780 for Seoul)
          latitude (float): Latitude coordinate (e.g., 37.5665 for Seoul)
          radius (int, optional): Search radius in meters (default: 1000, max: 20000)
          content_type (str, optional): Type of content to filter. Valid values:
              - "Tourist Attraction" (default)
              - "Cultural Facility"
              - "Festival Event"
              - "Leisure Activity"
              - "Accommodation"
              - "Shopping"
              - "Restaurant"
              - "Transportation"
          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: Nearby tourism attractions 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
              "search_radius": int,   # Search radius used
              "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
                      "dist": str             # Distance from the specified coordinates
                  }
                  # ... more items
              ]
          }
  
      Example:
          find_nearby_attractions(126.9780, 37.5665, 1000, "Tourist Attraction", "en", 1, 10)
      """
      # 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
      results = await get_api_client().get_location_based_list(
          mapx=longitude,
          mapy=latitude,
          radius=radius,
          content_type_id=content_type_id,
          language=language,
          page=page,
          rows=rows,
      )
      # Apply filter if provided
      if filter:
          filter_items = []
          for item in results.get("items", []):
              item = {k: v for k, v in item.items() if k in filter}
              filter_items.append(item)
          results["items"] = filter_items
      # Add search radius to the results
      return {**results, "search_radius": radius}