search_users
Find Weibo users by entering a keyword. Retrieve a list of user profiles with details such as names and handles, customizable with pagination and result limits for precise searches.
Instructions
Search for Weibo users based on a keyword.
Returns:
list[dict]: List of dictionaries containing user information
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | Search term to find users | |
| limit | No | Maximum number of users to return, defaults to 5 | |
| page | No | Page number for pagination, defaults to 1 |
Implementation Reference
- src/mcp_server_weibo/weibo.py:95-127 (handler)Core handler implementing the search_users tool logic: performs HTTP GET to Weibo search API with keyword, parses JSON response, extracts user cards, converts to UserProfile objects using _to_user_profile helper.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 using @mcp.tool() decorator. Defines input schema via Annotated[Field] parameters (keyword, limit, page) and delegates execution to WeiboCrawler instance.@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-31 (schema)Pydantic BaseModel defining the UserProfile schema, used as return type for individual users in search_users output (list[UserProfile]). Includes fields like id, screen_name, profile_image_url, etc.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()
- Helper function to convert raw Weibo user dict to structured UserProfile Pydantic model, used within search_users to process search results.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', '') )