Hong Kong Open Data MCP Server

Instructions

Implementation Reference

• src/mcp_open_data_hk/server.py:88-125 (handler)

  The @mcp.tool decorated async function implementing the list_categories MCP tool. It fetches data categories (groups) from the data.gov.hk API using the /group_list endpoint, handling parameters for sorting, pagination, fields, and language. The function signature and docstring define the input schema.

  @mcp.tool
  async def list_categories(
      order_by: str = "name",
      sort: str = "title asc",
      limit: Optional[int] = None,
      offset: Optional[int] = None,
      all_fields: bool = False,
      language: str = "en",
  ) -> Any:
      """
      Get a list of data categories (groups)
  
      Args:
          order_by: Field to sort by ('name' or 'packages') - deprecated, use sort instead
          sort: Sorting of results ('name asc', 'package_count desc', etc.)
          limit: Maximum number of categories to return
          offset: Offset for pagination
          all_fields: Return full group dictionaries instead of just names
          language: Language code (en, tc, sc)
      """
      base_url = BASE_URLS.get(language, BASE_URLS["en"])
      url = f"{base_url}/group_list"
  
      params = {"sort": sort, "all_fields": str(all_fields).lower()}
  
      if order_by != "name":  # Only add if not default
          params["order_by"] = order_by
  
      if limit is not None:
          params["limit"] = str(limit)
      if offset is not None:
          params["offset"] = str(offset)
  
      result = await make_api_request(url, params)
      if result.get("success"):
          return result["result"]
      else:
          raise Exception(f"API Error: {result.get('error', 'Unknown error')}")

• src/mcp_open_data_hk/server.py:19-30 (helper)

  Shared helper function used by list_categories (and other tools) to make HTTP requests to the data.gov.hk API endpoints.

  async def make_api_request(
      url: str, params: Optional[Dict[str, Any]] = None
  ) -> Dict[str, Any]:
      """Make an API request to data.gov.hk"""
      async with httpx.AsyncClient() as client:
          # Print the request for debugging
          print(f"Making request to {url} with params {params}")
          response = await client.get(url, params=params)
          print(f"Response status: {response.status_code}")
          response.raise_for_status()
          return response.json()