get_character_persons
Retrieve a formatted list of persons, such as voice actors, associated with a specific character using the character ID through Bangumi TV MCP Service.
Instructions
List persons (e.g., voice actors) related to a character.
Args:
character_id: The ID of the character.
Returns:
Formatted list of related persons or an error message.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| character_id | Yes |
Input Schema (JSON Schema)
{
"properties": {
"character_id": {
"title": "Character Id",
"type": "integer"
}
},
"required": [
"character_id"
],
"title": "get_character_personsArguments",
"type": "object"
}
Implementation Reference
- main.py:1058-1105 (handler)The primary handler for the 'get_character_persons' tool. Decorated with @mcp.tool(), it defines the schema from the signature and docstring, registers the tool, and implements the logic: calls Bangumi API /v0/characters/{character_id}/persons, handles errors, parses response, formats persons with type and role using PersonType enum.@mcp.tool() async def get_character_persons(character_id: int) -> str: """ List persons (e.g., voice actors) related to a character. Args: character_id: The ID of the character. Returns: Formatted list of related persons or an error message. """ response = await make_bangumi_request( method="GET", path=f"/v0/characters/{character_id}/persons" ) error_msg = handle_api_error_response(response) if error_msg: return error_msg # Expecting a list of persons if not isinstance(response, list): return f"Unexpected API response format for get_character_persons: {response}" persons = response if not persons: return f"No persons found related to character ID {character_id}." formatted_results = [] for person in persons: name = person.get("name") person_id = person.get("id") person_type_int = person.get("type") try: person_type_str = ( PersonType(person_type_int).name if person_type_int is not None else "Unknown Type" ) except ValueError: person_type_str = f"Unknown Type ({person_type_int})" staff_info = person.get("staff") # Role of the person for this character (e.g., formatted_results.append( f"Person ID: {person_id}, Name: {name}, Type: {person_type_str}, Role (for character): {staff_info}" ) return "Persons Related to This Character:\n" + "\n---\n".join(formatted_results)
- main.py:1371-1380 (helper)A helper prompt that instructs the LLM to use the 'get_character_persons' tool after searching for a character, specifically to find voice actors.@mcp.prompt() 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."