D&D MCP Server

Instructions

Implementation Reference

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

  The handler function for the 'bulk_update_characters' tool. It applies bulk changes to HP, temporary HP, and ability scores across multiple specified characters, clamping values appropriately and updating the storage.

  @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."

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

  The @mcp.tool decorator registers the bulk_update_characters function as an MCP tool.

  @mcp.tool

• src/gamemaster_mcp/main.py:240-249 (schema)

  Pydantic schema definitions for the tool parameters using Annotated and Field.

      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: