DraCor MCP Server

Instructions

Implementation Reference

• dracor_mcp_fastmcp.py:543-619 (handler)

  The handler function for the analyze_play_structure tool. It retrieves play metadata, metrics, characters, and spoken text data from the DraCor API, extracts structural elements like acts and scenes, computes gender counts and speaking distribution, and returns a comprehensive analysis dictionary.
  @mcp.tool() def analyze_play_structure(corpus_name: str, play_name: str) -> Dict: """Analyze the structure of a play including acts, scenes, and metrics.""" try: play = api_request(f"corpora/{corpus_name}/plays/{play_name}") metrics = api_request(f"corpora/{corpus_name}/plays/{play_name}/metrics") # Extract structural information from segments acts = [] scenes = [] for segment in play.get("segments", []): if segment.get("type") == "act": acts.append({ "number": segment.get("number"), "title": segment.get("title") }) elif segment.get("type") == "scene": scenes.append({ "number": segment.get("number"), "title": segment.get("title"), "speakers": segment.get("speakers", []) }) # Get character data characters = api_request(f"corpora/{corpus_name}/plays/{play_name}/characters") # Count characters by gender gender_counts = {"MALE": 0, "FEMALE": 0, "UNKNOWN": 0} for character in characters: gender = character.get("gender") if gender in gender_counts: gender_counts[gender] += 1 # Get spoken text by character data spoken_text_by_char = api_request(f"corpora/{corpus_name}/plays/{play_name}/spoken-text-by-character") # Calculate total words and distribution total_words = sum(char.get("numOfWords", 0) for char in characters) speaking_distribution = [] if total_words > 0: for char in characters: char_words = char.get("numOfWords", 0) speaking_distribution.append({ "character": char.get("name"), "words": char_words, "percentage": round((char_words / total_words) * 100, 2) }) # Sort by word count speaking_distribution.sort(key=lambda x: x["words"], reverse=True) # Get structural information structure = { "title": play.get("title"), "authors": [author.get("name") for author in play.get("authors", [])], "year": play.get("yearNormalized"), "yearWritten": play.get("yearWritten"), "yearPrinted": play.get("yearPrinted"), "yearPremiered": play.get("yearPremiered"), "acts": acts, "scenes": scenes, "numOfActs": len(acts), "numOfScenes": len(scenes), "segments": metrics.get("segments"), "dialogues": metrics.get("dialogues"), "wordCount": total_words, "characters": { "total": len(characters), "byGender": gender_counts }, "speakingDistribution": speaking_distribution[:10], # Top 10 characters by speaking time } return structure except Exception as e: return {"error": str(e)}