Bangumi TV MCP Service

Instructions

List characters voiced or portrayed by a person (e.g., voice actor, actor).

Args:
    person_id: The ID of the person.

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

Implementation Reference

• main.py:1292-1292 (registration)

  The @mcp.tool() decorator registers the function below as an MCP tool named 'get_person_characters' based on the function name.

  @mcp.tool()

• main.py:1293-1341 (handler)

  The main handler function that fetches characters related to a person by making an API request to Bangumi's /v0/persons/{person_id}/characters endpoint, processes the response, formats the output listing character IDs, names, types, and roles.

  async def get_person_characters(person_id: int) -> str:
      """
      List characters voiced or portrayed by a person (e.g., voice actor, actor).
  
      Args:
          person_id: The ID of the person.
  
      Returns:
          Formatted list of related characters or an error message.
      """
      response = await make_bangumi_request(
          method="GET", path=f"/v0/persons/{person_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_person_characters: {response}"
  
      characters = response
      if not characters:
          return f"No characters found related to person ID {person_id}."
  
      formatted_results = []
      for character in characters:
          name = character.get("name")
          char_id = character.get("id")
          char_type_int = character.get("type")
          try:
              char_type_str = (
                  CharacterType(char_type_int).name
                  if char_type_int is not None
                  else "Unknown Type"
              )
          except ValueError:
              char_type_str = f"Unknown Type ({char_type_int})"
  
          staff_info = character.get(
              "staff"
          )  # Role of the person for this character (e.g., Voice Actor name)
  
          formatted_results.append(
              f"Character ID: {char_id}, Name: {name}, Type: {char_type_str}, Role: {staff_info}"
          )
  
      return "Characters Related to This Person:\n" + "\n---\n".join(formatted_results)