Weibo MCP Server

Instructions

Search for Weibo users based on a keyword.
    
Returns:
    list[dict]: List of dictionaries containing user information

Implementation Reference

• src/mcp_server_weibo/weibo.py:95-127 (handler)

  Core handler logic for searching Weibo users by keyword, fetching data via API and parsing into UserProfile objects.

  async def search_users(self, keyword: str, limit: int = 5, page: int = 1) -> list[UserProfile]:
      """
      Search for Weibo users based on a keyword.
  
      Args:
          keyword (str): Search term to find users
          limit (int): Maximum number of users to return, defaults to 5
  
      Returns:
          list[UserProfile]: List of UserProfile objects containing user information
      """
      async with httpx.AsyncClient() as client:
          try:
              params = {
                  'containerid': f'100103type=3&q={keyword}',
                  'page_type': 'searchall',
                  'page': page,
              }
              encoded_params = urlencode(params)
  
              response = await client.get(f'{SEARCH_URL}?{encoded_params}', headers=DEFAULT_HEADERS)
              result = response.json()
              cards = result["data"]["cards"]
              if len(cards) < 2:
                  return []
              else:
                  cardGroup = cards[1]['card_group']
                  return [self._to_user_profile(item['user']) for item in cardGroup][:limit]
          except httpx.HTTPError:
              self.logger.error(
                  f"Unable to search users for keyword '{keyword}'", exc_info=True)
              return []

• src/mcp_server_weibo/server.py:14-27 (registration)

  MCP tool registration for 'search_users', defines input schema via Annotated Fields and delegates to WeiboCrawler.

  @mcp.tool()
  async def search_users(
      ctx: Context, 
      keyword: Annotated[str, Field(description="Search term to find users")], 
      limit: Annotated[int, Field(description="Maximum number of users to return, defaults to 5", default=5)] = 5,
      page: Annotated[int, Field(description="Page number for pagination, defaults to 1", default=1)] = 1
      ) -> list[dict]:
      """
      Search for Weibo users based on a keyword.
          
      Returns:
          list[dict]: List of dictionaries containing user information
      """
      return await crawler.search_users(keyword, limit, page)

• src/mcp_server_weibo/schemas.py:4-32 (schema)

  Pydantic model for UserProfile, used as return type in search_users (serialized to dict).

  class UserProfile(BaseModel):
      """
      Data model for a Weibo user's profile information.
      
      Attributes:
          id (int): User's unique identifier
          screen_name (str): User's display name
          profile_image_url (str): URL to user's profile image
          profile_url (str): URL to user's Weibo profile page
          description (str): User's profile description
          follow_count (int): Number of users the user is following
          followers_count (str): Number of followers (as string)
          avatar_hd (str): URL to user's high-resolution avatar image
          verified (bool): Whether the user is verified
          verified_reason (str): Reason for verification
          gender (str): User's gender
      """
      id: int = Field()
      screen_name: str = Field()
      profile_image_url: str = Field()
      profile_url: str = Field()
      description: str = Field()
      follow_count: int = Field()
      followers_count: str = Field()
      avatar_hd: str = Field()
      verified: bool = Field()
      verified_reason: str = Field()
      gender: str = Field()

• src/mcp_server_weibo/weibo.py:454-476 (helper)

  Helper function to convert raw API user data into structured UserProfile objects, called within search_users.

  def _to_user_profile(self, user: dict) -> UserProfile:
      """
      Convert raw user data to UserProfile object.
  
      Args:
          user (dict): Raw user data from Weibo API
  
      Returns:
          UserProfile: Formatted user profile information
      """
      return UserProfile(
          id = user['id'],
          screen_name = user['screen_name'],
          profile_image_url = user['profile_image_url'],
          profile_url = user['profile_url'], 
          description = user.get('description', ''),
          follow_count = user.get('follow_count', 0),
          followers_count = user.get('followers_count', ''),
          avatar_hd = user.get('avatar_hd', ''),
          verified = user.get('verified', False),
          verified_reason = user.get('verified_reason', ''),
          gender = user.get('gender', '')
      )