D&D MCP Server

Instructions

Implementation Reference

• src/gamemaster_mcp/main.py:238-320 (handler)

  The primary handler function for the 'bulk_update_characters' tool. Decorated with @mcp.tool, it processes bulk updates to multiple characters' hit points, temporary hit points, and ability scores by applying delta changes. It handles clamping values, logs updates, and reports on successes and failures.
  @mcp.tool def bulk_update_characters( names_or_ids: Annotated[list[str], Field(description="List of character names or IDs to update.")], hp_change: Annotated[int | None, Field(description="Amount to change current HP by (positive or negative).")] = None, temp_hp_change: Annotated[int | None, Field(description="Amount to change temporary HP by (positive or negative).")] = None, strength_change: Annotated[int | None, Field(description="Amount to change strength by.")] = None, dexterity_change: Annotated[int | None, Field(description="Amount to change dexterity by.")] = None, constitution_change: Annotated[int | None, Field(description="Amount to change constitution by.")] = None, intelligence_change: Annotated[int | None, Field(description="Amount to change intelligence by.")] = None, wisdom_change: Annotated[int | None, Field(description="Amount to change wisdom by.")] = None, charisma_change: Annotated[int | None, Field(description="Amount to change charisma by.")] = None, ) -> str: """Update properties for multiple characters at once by a given amount.""" updates_log = [] not_found_log = [] changes = { "hp_change": hp_change, "temp_hp_change": temp_hp_change, "strength_change": strength_change, "dexterity_change": dexterity_change, "constitution_change": constitution_change, "intelligence_change": intelligence_change, "wisdom_change": wisdom_change, "charisma_change": charisma_change, } # Filter out None changes active_changes = {k: v for k, v in changes.items() if v is not None} if not active_changes: return "No changes specified." for name_or_id in names_or_ids: character = storage.get_character(name_or_id) if not character: not_found_log.append(name_or_id) continue char_updates = {} char_log = [f"{character.name}:"] if hp_change is not None: new_hp = character.hit_points_current + hp_change # Clamp HP between 0 and max HP new_hp = max(0, min(new_hp, character.hit_points_max)) char_updates['hit_points_current'] = new_hp char_log.append(f"HP -> {new_hp}") if temp_hp_change is not None: new_temp_hp = character.temporary_hit_points + temp_hp_change # Temp HP cannot be negative new_temp_hp = max(0, new_temp_hp) char_updates['temporary_hit_points'] = new_temp_hp char_log.append(f"Temp HP -> {new_temp_hp}") abilities_updated = False ability_changes = { "strength": strength_change, "dexterity": dexterity_change, "constitution": constitution_change, "intelligence": intelligence_change, "wisdom": wisdom_change, "charisma": charisma_change } for ability, change in ability_changes.items(): if change is not None: new_score = character.abilities[ability].score + change new_score = max(1, min(new_score, 30)) # Clamp score character.abilities[ability].score = new_score abilities_updated = True char_log.append(f"{ability.capitalize()} -> {new_score}") if abilities_updated: char_updates['abilities'] = character.abilities if char_updates: storage.update_character(str(character.id), **char_updates) updates_log.append(" ".join(char_log)) response_parts = [] if updates_log: response_parts.append("Characters updated:\n" + "\n".join(updates_log)) if not_found_log: response_parts.append(f"Characters not found: {', '.join(not_found_log)}") return "\n".join(response_parts) if response_parts else "No characters found to update."