Bangumi TV MCP Service

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• main.py:883-934 (handler)

  Main execution logic for the search_characters tool. Registers the tool via @mcp.tool() decorator, handles API request to Bangumi search/characters endpoint, processes response, formats results using helper, and returns formatted text.
  @mcp.tool() async def search_characters( keyword: str, limit: int = 30, offset: int = 0, nsfw_filter: Optional[bool] = None ) -> str: """ Search for characters on Bangumi. Supported Character Types (integer enum in result): 1: Character, 2: Mechanic, 3: Ship, 4: Organization Args: keyword: The search keyword. limit: Pagination limit. Defaults to 30. offset: Pagination offset. Defaults to 0. nsfw_filter: Optional NSFW filter (boolean). Set to True to include, False to exclude. Requires authorization for non-default behavior. Returns: Formatted search results or an error message. """ json_body = {"keyword": keyword, "filter": {}} if nsfw_filter is not None: json_body["filter"]["nsfw"] = nsfw_filter # Filter is in JSON body params = {"limit": limit, "offset": offset} response = await make_bangumi_request( method="POST", path="/v0/search/characters", query_params=params, json_body=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_characters: {response}" characters = response.get("data", []) if not characters: return f"No characters found for keyword '{keyword}'." formatted_results = [format_character_summary(c) for c in characters] total = response.get("total", 0) results_text = ( f"Found {len(characters)} characters (Total matched: {total}).\n" + "---\n".join(formatted_results) ) return results_text
• main.py:244-267 (helper)

  Supporting function used by search_characters to format each character result into a concise summary string including type, name, ID, summary, and image URL.
  def format_character_summary(character: Dict[str, Any]) -> str: """Formats a character dictionary into a readable summary string.""" character_id = character.get("id") name = character.get("name") char_type = character.get("type") # Integer enum summary = character.get("short_summary") or character.get("summary", "") try: type_str = ( CharacterType(char_type).name if char_type is not None else "Unknown Type" ) except ValueError: type_str = f"Unknown Type ({char_type})" formatted_string = f"[{type_str}] {name} (ID: {character_id})\n" if summary: formatted_summary = summary # [:200] + '...' if len(summary) > 200 else summary formatted_string += f" Summary: {formatted_summary}\n" images = character.get("images") if images and images.get("common"): formatted_string += f" Image: {images.get('common')}\n" return formatted_string
• main.py:1372-1380 (helper)

  MCP prompt that demonstrates usage of search_characters tool as part of a workflow to find voice actors for a character.
  def find_voice_actor(character_name: str) -> str: """ Search for a character by name and find their voice actor. Args: character_name: The name of the character. """ return f"Search for the character '{character_name}' using 'search_characters'. If the search finds characters, identify the most relevant character ID. Then, use 'get_character_persons' with the character ID to list persons related to them (like voice actors). Summarize the voice actors found from the tool output."