search_subjects
Search for subjects like books, anime, music, games, or real-world content on Bangumi. Filter by type, sort by match, heat, rank, or score, and paginate results for precise discovery.
Instructions
Search for subjects on Bangumi.
Supported Subject Types (integer enum):
1: Book, 2: Anime, 3: Music, 4: Game, 6: Real
Supported Sort orders (string enum):
'match', 'heat', 'rank', 'score'
Args:
keyword: The search keyword.
subject_type: Optional filter by subject type. Use integer values (1, 2, 3, 4, 6).
sort: Optional sort order. Defaults to 'match'.
limit: Pagination limit. Max 50. Defaults to 30.
offset: Pagination offset. Defaults to 0.
Returns:
Formatted search results or an error message.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | ||
| limit | No | ||
| offset | No | ||
| sort | No | match | |
| subject_type | No |
Input Schema (JSON Schema)
{
"$defs": {
"SubjectType": {
"description": "条目类型\n1 = book, 2 = anime, 3 = music, 4 = game, 6 = real",
"enum": [
1,
2,
3,
4,
6
],
"title": "SubjectType",
"type": "integer"
}
},
"properties": {
"keyword": {
"title": "Keyword",
"type": "string"
},
"limit": {
"default": 30,
"title": "Limit",
"type": "integer"
},
"offset": {
"default": 0,
"title": "Offset",
"type": "integer"
},
"sort": {
"default": "match",
"title": "Sort",
"type": "string"
},
"subject_type": {
"anyOf": [
{
"$ref": "#/$defs/SubjectType"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"keyword"
],
"title": "search_subjectsArguments",
"type": "object"
}
Implementation Reference
- main.py:379-439 (handler)The core handler function for the 'search_subjects' tool, decorated with @mcp.tool() for automatic registration and schema generation from type hints. Performs POST request to Bangumi API /v0/search/subjects, processes response, handles errors, and formats results using helper functions.@mcp.tool() async def search_subjects( keyword: str, subject_type: Optional[SubjectType] = None, sort: str = "match", limit: int = 30, offset: int = 0, ) -> str: """ Search for subjects on Bangumi. Supported Subject Types (integer enum): 1: Book, 2: Anime, 3: Music, 4: Game, 6: Real Supported Sort orders (string enum): 'match', 'heat', 'rank', 'score' Args: keyword: The search keyword. subject_type: Optional filter by subject type. Use integer values (1, 2, 3, 4, 6). sort: Optional sort order. Defaults to 'match'. limit: Pagination limit. Max 50. Defaults to 30. offset: Pagination offset. Defaults to 0. Returns: Formatted search results or an error message. """ json_body = {"keyword": keyword, "sort": sort, "filter": {}} if subject_type is not None: json_body["filter"]["type"] = [int(subject_type)] params = {"limit": min(limit, 50), "offset": offset} # Enforce max limit response = await make_bangumi_request( method="POST", path="/v0/search/subjects", query_params=params, # Pass limit/offset as query params json_body=json_body, # Pass keyword and filter as JSON body ) error_msg = handle_api_error_response(response) if error_msg: return error_msg # Expecting a dictionary with 'data' and 'total' if not isinstance(response, dict) or "data" not in response: return f"Unexpected API response format for search_subjects: {response}" subjects = response.get("data", []) if not subjects: return f"No subjects found for keyword '{keyword}'." formatted_results = [format_subject_summary(s) for s in subjects] total = response.get("total", 0) results_text = ( f"Found {len(subjects)} subjects (Total matched: {total}).\n" + "---\n".join(formatted_results) ) return results_text
- main.py:26-37 (schema)Enum defining valid subject types used as the type for the 'subject_type' parameter in the search_subjects tool (and others), providing input validation and schema generation.class SubjectType(IntEnum): """ 条目类型 1 = book, 2 = anime, 3 = music, 4 = game, 6 = real """ BOOK = 1 ANIME = 2 MUSIC = 3 GAME = 4 REAL = 6
- main.py:208-242 (helper)Helper function used by search_subjects (and other subject-listing tools) to format each subject into a readable summary string including type, names, score, rank, summary, and image.def format_subject_summary(subject: Dict[str, Any]) -> str: """Formats a subject dictionary into a readable summary string.""" name = subject.get("name") name_cn = subject.get("name_cn") subject_type = subject.get("type") subject_id = subject.get("id") score = subject.get("rating", {}).get("score") # Access Nested Score rank = subject.get("rating", {}).get("rank") # Access Nested Rank summary = subject.get("short_summary") or subject.get("summary", "") try: type_str = ( SubjectType(subject_type).name if subject_type is not None else "Unknown Type" ) except ValueError: type_str = f"Unknown Type ({subject_type})" formatted_string = f"[{type_str}] {name_cn or name} (ID: {subject_id})\n" if score is not None: formatted_string += f" Score: {score}\n" if rank is not None: formatted_string += f" Rank: {rank}\n" if summary: formatted_summary = summary # [:200] + '...' if len(summary) > 200 else summary formatted_string += f" Summary: {formatted_summary}\n" # Add images URL if available (for potential LLM multi-modal future use or user info) images = subject.get("images") if images and images.get("common"): formatted_string += f" Image: {images.get('common')}\n" # Or 'grid', 'large', 'medium', 'small' depending on preference return formatted_string