Bangumi TV MCP Service

Instructions

List characters related to a subject.

Args:
    subject_id: The ID of the subject.

Returns:
    Formatted list of related characters or an error message.

Implementation Reference

• main.py:652-701 (handler)

  The handler function decorated with @mcp.tool(), implementing the logic to retrieve and format characters related to a given subject ID from the Bangumi API.

  @mcp.tool()
  async def get_subject_characters(subject_id: int) -> str:
      """
      List characters related to a subject.
  
      Args:
          subject_id: The ID of the subject.
  
      Returns:
          Formatted list of related characters or an error message.
      """
      response = await make_bangumi_request(
          method="GET", path=f"/v0/subjects/{subject_id}/characters"
      )
  
      error_msg = handle_api_error_response(response)
      if error_msg:
          return error_msg
  
      # Expecting a list of characters
      if not isinstance(response, list):
          return f"Unexpected API response format for get_subject_characters: {response}"
  
      characters = response
      if not characters:
          return f"No characters found related to subject ID {subject_id}."
  
      formatted_results = []
      for character in characters:
          name = character.get("name")
          char_id = character.get("id")
          relation = character.get("relation")
          actors = ", ".join(
              [a.get("name") for a in character.get("actors", []) if a.get("name")] or []
          )
  
          # Safely get character type name
          char_type_int = character.get("type")
          char_type_str = "Unknown Type"
          if char_type_int is not None:
              try:
                  char_type_str = CharacterType(char_type_int).name
              except ValueError:
                  char_type_str = f"Unknown Type ({char_type_int})"
  
          formatted_results.append(
              f"Character ID: {char_id}, Name: {name}, Type: {char_type_str}, Relation (in subject): {relation}, Voice Actors: {actors}"
          )
  
      return "Related Characters:\n" + "\n---\n".join(formatted_results)