search_by_keyword

Instructions

Implementation Reference

• src/mcp_kakao_local/server.py:65-97 (handler)

  MCP tool handler for 'search_by_keyword'. Defines input schema with Pydantic Fields, performs validation assertions, calls the KakaoLocalClient helper, and handles exceptions. This is the primary execution logic for the tool.

  @mcp.tool(description="Searches for places related to the keyword")
  async def search_by_keyword(
    keyword: str = Field(description="keyword used to search for places", min_length=1),
    category_group_code: CategoryGroupCode | None = Field(
      None, description="category used for filtering results (CategoryGroupCode resource)"
    ),
    center_coordinate: Coordinate | None = Field(
      None, description="longitude and latitude of a center"
    ),
    radius_from_center: int | None = Field(
      None, description="search radius from the center in meters", gt=0
    ),
    page: int = Field(1, description="page number of result", ge=1),
  ) -> LocationSearchResponse:
    """
    Returns:
      LocationSearchResponse: An object containing metadata and a list of places.
    """
    if center_coordinate:
      assert radius_from_center is not None
    if radius_from_center:
      assert center_coordinate is not None
  
    try:
      return await kakao_local_client.search_by_keyword(
        keyword,
        category_group_code,
        center_coordinate,
        radius_from_center,
        page=page,
      )
    except Exception as ex:
      return {"success": False, "error": str(ex)}

• src/mcp_kakao_local/kakao_local_client.py:40-63 (helper)

  Helper function in KakaoLocalClient that constructs the API request parameters and makes the HTTP GET request to Kakao's /search/keyword endpoint, then parses the response into LocationSearchResponse.

  async def search_by_keyword(
    self,
    keyword: str,
    category_group_code: CategoryGroupCode | None,
    center: Coordinate | None,
    radius: int | None,
    page: int = 1,
    size: int = 10,
    sort_option: LocationSortOption = LocationSortOption.ACCURACY,
  ) -> LocationSearchResponse:
    """https://developers.kakao.com/docs/latest/ko/local/dev-guide#search-by-keyword"""
    path = f"{self.BASE_URL}/search/keyword"
    params = {
      "query": keyword,
      "category_group_code": category_group_code.name if category_group_code else None,
      "x": center.longitude if center else None,
      "y": center.latitude if center else None,
      "radius": radius if radius else None,
      "page": page,
      "size": size,
      "sort": sort_option.value,
    }
    response_json = await self._get(path, {k: v for k, v in params.items() if v is not None})
    return LocationSearchResponse(**response_json)

• src/mcp_kakao_local/models.py:87-90 (schema)

  Pydantic model defining the output schema for the search_by_keyword tool response, including metadata and list of place documents.

  class LocationSearchResponse(BaseModel):
    meta: Meta = Field(description="Response metadata")
    documents: list[PlaceDocument] = Field(description="List of places")

• src/mcp_kakao_local/models.py:6-9 (schema)

  Pydantic model for coordinate input used in search_by_keyword tool parameters.

  class Coordinate(BaseModel):
    longitude: str
    latitude: str

• src/mcp_kakao_local/models.py:16-35 (schema)

  Enum defining valid category_group_code values used as input parameter type in search_by_keyword tool.

  class CategoryGroupCode(Enum):
    MT1 = "대형마트 (Large Mart, Grocery Store)"
    CS2 = "편의점 (Convenience Store)"
    PS3 = "어린이집, 유치원 (Daycare, Kindergarten)"
    SC4 = "학교 (School)"
    AC5 = "학원 (Academy/Private Institute)"
    PK6 = "주차장 (Parking Lot)"
    OL7 = "주유소, 충전소 (Gas Station, Charging Station)"
    SW8 = "지하철역 (Subway Station)"
    BK9 = "은행 (Bank)"
    CT1 = "문화시설 (Cultural Facility)"
    AG2 = "중개업소 (Agency, e.g. Real Estate)"
    PO3 = "공공기관 (Public Institution)"
    AT4 = "관광명소 (Tourist Attraction)"
    AD5 = "숙박 (Accommodation)"
    FD6 = "음식점 (Restaurant)"
    CE7 = "카페 (Cafe)"
    HP8 = "병원 (Hospital)"
    PM9 = "약국 (Pharmacy)"