analyze_play_structure
Analyze acts, scenes, and structural metrics of plays using the Drama Corpora Project API. Input corpus and play names to examine dramatic texts across languages and periods.
Instructions
Analyze the structure of a play including acts, scenes, and metrics.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| corpus_name | Yes | ||
| play_name | Yes |
Implementation Reference
- dracor_mcp_fastmcp.py:543-619 (handler)The handler function decorated with @mcp.tool() that implements the analyze_play_structure tool. It fetches play metadata, metrics, characters, and computes structural analysis including acts, scenes, character counts by gender, and speaking distribution.@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)}