Hubble MCP Server

Instructions

Implementation Reference

• data_api.py:305-350 (handler)

  The handler function implementing the core logic of the 'get_keyword_info' tool. It is registered via @mcp.tool() decorator and handles the API request to retrieve keyword information using KeywordParameters.
  @async_retry(exceptions=(Exception), tries=2, delay=0.3) async def get_keyword_info( req_param: KeywordParameters) -> dict[KeywordResponse, Any] | None: ''' 키워드 정보 조회 (최대 1000개 키워드 조회 가능) 모든 키워드는 소문자로 변환하여 요청 키워드 정보 조회 결과는 키워드 정보 조회 결과 형식에 따라 반환됩니다. args: req_param: KeywordParameters, 키워드 정보 조회 요청 파라미터 returns: dict[KeywordResponse, Any] | None: 키워드 정보 조회 결과 KeywordResponse 는 아래와 같은 정보를 포함합니다: ads_metrics: - competition: 경쟁도 수준 (LOW: 0-33, MEDIUM: 34-66, HIGH: 67-100) - competition_index: 구글 검색광고 경쟁도 (0-100) - cpc: 클릭당 비용 - volume_avg: 최근 3개월 월평균 검색량 - volume_total: 최근 12개월 총 검색량 - volume_trend: 3개월 전 대비 검색량 증감율 - gg_volume_avg: 구글 최근 3개월 월평균 검색량 - gg_volume_total: 구글 최근 12개월 총 검색량 - gg_volume_trend: 구글 검색량 증감율 - nv_volume_avg: 네이버 최근 3개월 월평균 검색량 - nv_volume_total: 네이버 최근 12개월 총 검색량 - nv_volume_trend: 네이버 검색량 증감율 intents: - I: Informational - 잠재 소비자가 제품 자체 정보나 제품이 포함된 카테고리 등에 대한 정보를 얻기 위한 검색 - N: Navigational - 잠재 소비자가 특정 웹사이트나 브랜드 혹은 매장 위치를 찾기 위한 검색 - C: Commercial - 구매 전 단계에서 비교, 리뷰, 추천 등의 구매 의사 결정에 도움이 되는 정보를 구하려는 목적의 검색 - T: Transactional - 구매를 목적으로 하는 검색 monthly_volume: - month: 해당 월 - gg: 구글 검색량 - nv: 네이버 검색량 - total: 구글 + 네이버 검색량 ''' async with httpx.AsyncClient() as client: headers = {"X-API-Key": HUBBLE_API_KEY} response = await client.post( f"{HUBBLE_API_URL}/keyword", headers=headers, json=req_param.model_dump(), timeout=30.0) response.raise_for_status() return response.text
• data_api.py:39-61 (schema)

  Input schema (KeywordParameters) used by the get_keyword_info handler for validating input parameters like keywords list and geolocation.
  class KeywordParameters(BaseModel): keywords: List = Field( min_items=1, max_items=1000, title="keyword(list)", description="요청 키워드", ) ''' gl: Geolocation of end user. https://www.link-assistant.com/news/googles-gl-parameter-explained.html https://developers.google.com/custom-search/v1/reference/rest/v1/cse/list#:~:text=Geolocation%20of%20end%20user. ''' gl: Literal['kr', 'jp'] = Field( default='kr', title="Geolocation", description="국가 코드", ) _request_at: str _api_key: str def __init__(self, **data): super().__init__(**data) self._request_at = datetime.now(UTC).isoformat(timespec='milliseconds') + 'Z' # yapf:disable class AdsMetrics(BaseModel):
• data_api.py:61-89 (schema)

  Supporting schema (AdsMetrics) used within KeywordInfo for advertisement metrics in the tool's response.
  class AdsMetrics(BaseModel): # https://developers.google.com/google-ads/api/reference/rpc/v17/KeywordPlanCompetitionLevelEnum.KeywordPlanCompetitionLevel competition: Optional[str] = Field(default=None, description=""" competition_index 범위에 따른 구분값 * LOW: 0~33 * MEDIUM: 34~66 * HIGH: 67~100""") competition_index: Optional[int] = Field( default=None, description="구글 검색광고 경쟁도 (검색광고 슬롯 판매 비율)") cpc: Optional[float] = Field(default=None) low_bid_micros: Optional[int] = Field(default=None) high_bid_micros: Optional[int] = Field(default=None) volume_avg: Optional[int] = Field(description="최근 3개월의 월별 검색량 평균값") volume_total: Optional[int] = Field(description="최근 12개월의 월별 검색량 합산값") volume_trend: Optional[float] = Field( description="3개월 전 대비 최근 월 검색량 증감율") gg_volume_avg: Optional[int] = Field(description="(구글)최근 3개월의 월 검색량 평균값") gg_volume_total: Optional[int] = Field( description="(구글)최근 12개월의 월 검색량 합산값") gg_volume_trend: Optional[float] = Field( description="(구글)3개월 전 대비 최근 월 검색량 증감율") nv_volume_avg: Optional[int] = Field( description="(네이버)최근 3개월의 월 검색량 평균값") nv_volume_total: Optional[int] = Field( description="(네이버)최근 12개월의 월 검색량 합산값") nv_volume_trend: Optional[float] = Field( description="(네이버)3개월 전 대비 최근 월 검색량 증감율") class KeywordInfo(BaseModel):
• data_api.py:89-172 (schema)

  Core response schema component (KeywordInfo) detailing keyword features, intents, demography, and volumes.
  class KeywordInfo(BaseModel): keyword: str ads_metrics: Optional[AdsMetrics] = Field(default=None) features: Optional[object] = Field(default=None, description=""" 해당 키워드의 검색 결과 페이지(SERP)에 어떤 검색 스니펫(아래 리스트 참조)이 노출 되고 있는 지를 제공합니다. > https://kr.listeningmind.com/hubble-guide/filter-serp-type/ 존재하는 검색 스니펫 타입 종류는 아래와 같습니다. * f_ad_bottom: 검색 결과 하단에 존재하는 광고 (해당 키워드가 상업형 혹은 거래형 키워드일 가능성을 보여줌) * f_ad_top: 검색 결과 상단에 존재하는 광고 (해당 키워드가 상업형 혹은 거래형 키워드일 가능성을 보여줌) * f_ads_bottom: 검색 결과 하단에 존재하는 광고 (해당 키워드가 상업형 혹은 거래형 키워드일 가능성을 보여줌) * f_ads_top: 검색 결과 상단에 존재하는 광고 (해당 키워드가 상업형 혹은 거래형 키워드일 가능성을 보여줌) * f_adult_certification: 성인 인증이 필요한 검색 결과 * f_app_results: 앱 검색 결과 * f_articles: 뉴스 기사 검색 결과 (해당 키워드가 뉴스성이 있는 키워드임을 보여줌) * f_featured_snippet: 구글의 피쳐드 스니펫 * f_featured_snippet_ordered_list: 구글의 피쳐드 스니펫 중 순서가 있는 리스트 * f_featured_snippet_table: 구글의 피쳐드 스니펫 중 표 형태로 제공되는 리스트 * f_featured_snippet_unordered_list: 구글의 피쳐드 스니펫 중 순서가 없는 리스트 * f_featured_snippet_video_exist: 구글의 피쳐드 스니펫 중 비디오가 포함된 리스트 * f_google_play: 구글 플레이 검색 결과 (해당 키워드가 앱과 관련된 키워드임을 보여줌) * f_images: 이미지 검색 결과 (해당 키워드가 이미지 검색 결과가 있는 키워드임을 보여줌) * f_job_search: 구글의 구인 검색 결과 (해당 키워드가 구인과 관련된 키워드임을 보여줌) * f_knowledge_panel: 구글의 지식 패널 검색 결과 (해당 키워드가 브랜드나 인물 등과 관련된 키워드임을 보여줌) * f_local_results: 구글의 로컬 검색 결과 (해당 키워드가 지역과 관련된 키워드임을 보여줌) * f_organic_results: 구글의 유기적 검색 결과 * f_organic_results_rating: 구글의 유기적 검색 결과 중 평점이 있는 검색 결과 (해당 키워드의 제품이나 브랜드가 리뷰나 평점을 받고 있음을 보여줌) * f_organic_results_video: 구글의 유기적 검색 결과 중 비디오가 포함된 검색 결과 (해당 키워드가 비디오 포맷의 콘텐츠에 대한 니즈를 가질 가능성 혹은 유튜브에서도 검색되는 키워드임을 보여줌) * f_others: 기타 검색 결과 * f_people_also_ask_for: 구글의 People Also Ask 검색 결과 * f_people_also_search_for: 구글의 People Also Search For 검색 결과 * f_product_comparison: 제품 비교 검색 결과 * f_related_searches: 구글의 Related Searches 검색 결과 * f_safe_search: 안전 검색이 적용된 검색 결과 (해당 키워드가 안전 검색이 적용된 키워드임을 보여줌) * f_scholar: 구글 스칼라 검색 결과 (해당 키워드가 학술적이거나 연구 관련된 키워드임을 보여줌) * f_sitelinks: 구글의 사이트 링크 검색 결과 (해당 키워드가 특정 웹사이트나 브랜드와 관련된 키워드임을 보여줌) * f_sns: 소셜 미디어 검색 결과 (해당 키워드가 소셜 미디어에서 급상승 혹은 관련 맨션이 많은 키워드임을 보여줌) * f_spell_check: 구글의 스펠링 검사 검색 결과 (해당 키워드가 오타 혹은 일반적으로 상요되는 다른 표현이 있는 키워드임을 보여줌) * f_sticky_header_tabs: 구글의 스티키 헤더 탭 검색 결과 (해당 키워드가 검색 결과 상단에 탭 형태로 제공되는 키워드임을 보여줌) * f_unit_converter: 단위 변환 검색 결과 * f_unknown: 구글의 알수 없는 검색 결과 * f_video_carousels: 구글의 비디오 캐러셀 검색 결과 (해당 키워드가 비디오 포맷의 콘텐츠에 대한 니즈를 가질 가능성 혹은 유튜브에서도 검색되는 키워드임을 보여줌) * f_video_results: 구글의 비디오 검색 결과 (해당 키워드가 비디오 포맷의 콘텐츠에 대한 니즈를 가질 가능성 혹은 유튜브에서도 검색되는 키워드임을 보여줌) """) intents: Optional[object] = Field(default=None, description=""" 검색 인텐트(https://www.ascentkorea.com/what-is-search-intent/) * I: 정보형(Informational)잠재 소비자가 제품 자체 정보나 제품이 포함된 카테고리 등에 대한 정보를 얻기 위한 검색 * N: 네비게이셔널형(Navigational)잠재 소비자가 특정 웹사이트나 브랜드 혹은 매장 위치를 찾기 위한 검색 * C: 상업형(Commercial) 구매 전 단계에서 비교, 리뷰, 추천 등의 구매 의사 결정에 도움이 되는 정보를 구하려는 목적의 검색 * T: 거래형(Transactional)구매를 목적으로 하는 검색 """) demography: Optional[object] = Field(default=None, description=""" 검색 유저 특성(https://kr.listeningmind.com/hubble-guide/filter-user/) * m_gender: 표준편차 (시그마 1) 이상으로 남성이 더 많이 검색했을 가능성이 높은 키워드 * f_gender: 표준편차 (시그마 1) 이상으로 여성이 더 많이 검색했을 가능성이 높은 키워드 * a0: 표준편차 (시그마 1) 이상으로 12세 이하가 더 많이 검색했을 가능성이 높은 키워드 * a13: 표준편차 (시그마 1) 이상으로 13~19세가 더 많이 검색했을 가능성이 높은 키워드 * a20: 표준편차 (시그마 1) 이상으로 20~24세가 더 많이 검색했을 가능성이 높은 키워드 * a25: 표준편차 (시그마 1) 이상으로 25~29세가 더 많이 검색했을 가능성이 높은 키워드 * a30: 표준편차 (시그마 1) 이상으로 30~39세가 더 많이 검색했을 가능성이 높은 키워드 * a40: 표준편차 (시그마 1) 이상으로 40~49세가 더 많이 검색했을 가능성이 높은 키워드 * a50: 50세 이상이 더 많이 검색했을 가능성이 높은 키워드 * m_gender_ratio: 남성 검색자의 비율 * f_gender_ratio: 여성 검색자의 비율 * a0_ratio: 12세 이하 검색자의 비율 * a13_ratio: 13~19세 검색자의 비율 * a20_ratio: 20~24세 검색자의 비율 * a25_ratio: 25~29세 검색자의 비율 * a30_ratio: 30~39세 검색자의 비율 * a40_ratio: 40~49세 검색자의 비율 * a50_ratio: 50세 이상 검색자의 비율 """) monthly_volume: Optional[List[object]] = Field(default=None, description=""" 월별 검색량 * month: 해당 월 * gg: 구글 검색량 * nv: 네이버 검색량 * total: 구글 검색량 + 네이버 검색량 """) class KeywordData(BaseModel): infos: Optional[List[KeywordInfo]]
• data_api.py:189-193 (schema)

  Output response schema (KeywordResponse) wrapping the keyword data and metadata.
  class KeywordResponse(BaseResponse): request_detail: KeywordParameters = Field(description="요청 받았던 파라미터") cost: int = Field(default=0) remain_credits: int = Field(default=-1) data: Optional[KeywordData] = Field(default=None)