Hubble MCP Server

Instructions

Implementation Reference

• data_api.py:381-401 (handler)

  The core handler function for the 'crawl_google_serp' MCP tool, registered via the @mcp.tool() decorator. Includes an async retry wrapper. Proxies parameters to an internal Hubble API endpoint '/google_serp' and returns the raw text response typed against SerpResponse schema.

  @mcp.tool()
  @async_retry(exceptions=(Exception), tries=2, delay=0.3)
  async def crawl_google_serp(
          keyword: str,
          gl: Literal['kr', 'us', 'jp'] = "kr") -> dict[SerpResponse, Any] | None:
      '''
      구글 SERP API 요청
      '''
      async with httpx.AsyncClient() as client:
          payload = {
              "keyword": keyword,
              "gl": gl
          }
          headers = {"X-API-Key": HUBBLE_API_KEY}
          response = await client.post(
              f"{HUBBLE_API_URL}/google_serp",
              headers=headers,
              json=payload,
              timeout=30.0)
          response.raise_for_status()
          return response.text

• data_api.py:272-278 (schema)

  Pydantic BaseModel defining the structure of the SERP response (output schema for the tool), inheriting from BaseResponse. Includes request details, cost, credits, and data list.

  class SerpResponse(BaseResponse):
      """SERP 응답 형식
      """
      request_detail: SerpParameters = Field(description="요청 받았던 파라미터")
      cost: int = Field(default=0, title="", description="")
      remain_credits: int = Field(default=-1, title="", description="")
      data: Optional[List[dict]] = Field(default=None, title="", description="")

• data_api.py:381-381 (registration)

  The @mcp.tool() decorator registers the crawl_google_serp function as an MCP tool.

  @mcp.tool()