Bangumi TV MCP Service

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.

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