Hubble MCP Server

Instructions

Implementation Reference

• data_api.py:305-350 (handler)

  Full implementation of the 'get_keyword_info' tool handler. Registered via @mcp.tool(), includes retry decorator, detailed docstring describing inputs/outputs, and HTTP POST to external Hubble API /keyword endpoint with 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)

  Pydantic schema (BaseModel) for input parameters to the get_keyword_info tool: list of keywords (1-1000), gl ('kr' or 'jp'), and internal timestamp/API key fields.
  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:190-194 (schema)

  Pydantic schema for the output response of the get_keyword_info tool, extending BaseResponse, including request details, cost, credits, and KeywordData.
  request_detail: KeywordParameters = Field(description="요청 받았던 파라미터") cost: int = Field(default=0) remain_credits: int = Field(default=-1) data: Optional[KeywordData] = Field(default=None) class ClusterParameters(BaseModel):