Bangumi TV MCP Service

Instructions

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.

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."