Bangumi TV MCP Service

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• main.py:1005-1056 (handler)

  The main handler function for the 'get_character_subjects' tool. It is decorated with @mcp.tool() which also serves as registration. Fetches related subjects for a given character ID from the Bangumi API endpoint /v0/characters/{character_id}/subjects, handles API errors, validates response format, formats each subject with name, type, and role info, and returns a formatted string summary.
  @mcp.tool() async def get_character_subjects(character_id: int) -> str: """ List subjects (e.g., anime, games) where a character appears. Args: character_id: The ID of the character. Returns: Formatted list of related subjects or an error message. """ response = await make_bangumi_request( method="GET", path=f"/v0/characters/{character_id}/subjects" ) error_msg = handle_api_error_response(response) if error_msg: return error_msg # Expecting a list of subjects if not isinstance(response, list): return f"Unexpected API response format for get_character_subjects: {response}" related_subjects = response if not related_subjects: return f"No subjects found related to character ID {character_id}." formatted_results = [] for rel_subject in related_subjects: name = rel_subject.get("name") name_cn = rel_subject.get("name_cn") rel_id = rel_subject.get("id") rel_type_int = rel_subject.get("type") try: rel_type_str = ( SubjectType(rel_type_int).name if rel_type_int is not None else "Unknown Type" ) except ValueError: rel_type_str = f"Unknown Type ({rel_type_int})" staff_info = rel_subject.get( "staff" ) # Staff refers to the role of the char in the subject e.g. "主角" formatted_results.append( f"Subject ID: {rel_id}, Name: {name_cn or name}, Type: {rel_type_str}, Role/Staff (in subject): {staff_info}" ) return "Subjects This Character Appears In:\n" + "\n---\n".join(formatted_results)
• main.py:208-241 (helper)

  Helper function used by get_character_subjects (and others) to format individual subject summaries with type, name, 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
• main.py:105-169 (helper)

  Core helper function used by all Bangumi API tools, including get_character_subjects, to make HTTP requests with authentication, error handling, and debug logging.
  async def make_bangumi_request( method: str, path: str, query_params: Optional[Dict[str, Any]] = None, json_body: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None, ) -> Any: """Make a request to the Bangumi API with proper headers and error handling.""" request_headers = headers.copy() if headers else {} request_headers["User-Agent"] = USER_AGENT request_headers["Accept"] = "application/json" if BANGUMI_TOKEN: request_headers["Authorization"] = f"Bearer {BANGUMI_TOKEN}" url = f"{BANGUMI_API_BASE}{path}" async with httpx.AsyncClient() as client: try: print( f"DEBUG: Making {method} request to {url} with params={query_params}, json={json_body}" ) response = await client.request( method=method, url=url, params=query_params, json=json_body, headers=request_headers, timeout=30.0, ) response.raise_for_status() # Return the raw JSON response, let the calling tool handle its structure (dict or list) json_response = response.json() print( f"DEBUG: Received response (type: {type(json_response)}, keys/length: {list(json_response.keys()) if isinstance(json_response, dict) else len(json_response) if isinstance(json_response, list) else 'N/A'})" ) return json_response except httpx.HTTPStatusError as e: error_msg = ( f"HTTP error occurred: {e.response.status_code} - {e.response.text}" ) print(f"ERROR: {error_msg}") # Try to parse the error response body if it's JSON try: error_details = e.response.json() return { "error": error_msg, "status_code": e.response.status_code, "details": error_details, } except json.JSONDecodeError: return { "error": error_msg, "status_code": e.response.status_code, "details": e.response.text, } except httpx.RequestError as e: error_msg = f"An error occurred while requesting {e.request.url!r}: {e}" print(f"ERROR: {error_msg}") return {"error": error_msg} except Exception as e: error_msg = f"An unexpected error occurred: {e}" print(f"ERROR: {error_msg}") return {"error": error_msg}
• main.py:172-205 (helper)

  Helper function used by get_character_subjects (and all tools) to detect and format API error responses from make_bangumi_request or direct API errors.
  def handle_api_error_response(response: Any) -> Optional[str]: """ Checks if the API response indicates an error and returns a formatted error message. Handles both dictionary-based errors and returns from make_bangumi_request on failure. """ # Check for error structure returned by make_bangumi_request on HTTPStatusError or RequestError if isinstance(response, dict) and ( "error" in response or "status_code" in response ): # This is an error dictionary created by our helper status_code = response.get("status_code", "N/A") error_msg = response.get("error", "Unknown error during request.") details = response.get("details", "") return f"Bangumi API Request Error (Status {status_code}): {error_msg}. Details: {details}".strip() # Check for error structure returned by Bangumi API itself (often dictionaries) # Safely check if the response is a dictionary before accessing its keys if isinstance(response, dict): if "title" in response and "description" in response: # This looks like a common Bangumi error response structure error_title = response.get("title", "API Error") error_description = response.get("description", "No description provided.") # The API might return a status code in the body too, or rely on HTTP status return f"Bangumi API Error: {error_title}. {error_description}".strip() # Check if it's a dictionary but *not* empty and *doesn't* look like a success response from list endpoints # Check for specific error fields if structure varies # Add more checks here if other error dictionary formats are observed # Example: if "message" in response and "code" in response: return f"API Error {response['code']}: {response['message']}" pass # If it's a dictionary but doesn't match known error formats, assume it's a valid data response for now # If it's not a dictionary, or it's a dictionary that doesn't match known error formats, assume it's not an error return None
• main.py:1005-1005 (registration)

  The @mcp.tool() decorator registers the get_character_subjects function as an MCP tool.
  @mcp.tool()