D&D MCP Server

Instructions

Implementation Reference

• src/gamemaster_mcp/main.py:202-236 (handler)

  MCP tool handler for 'update_character', including registration via @mcp.tool decorator and input schema via Annotated parameters with Field descriptions. Handles fetching character, preparing updates, calling storage, and returning confirmation.

  def update_character(
      name_or_id: Annotated[str, Field(description="The name or ID of the character to update.")],
      name: Annotated[str | None, Field(description="New character name. If you change this, you must use the character's ID to identify them.")] = None,
      player_name: Annotated[str | None, Field(description="The name of the player in control of this character")] = None,
      description: Annotated[str | None, Field(description="A brief description of the character's appearance and demeanor.")] = None,
      bio: Annotated[str | None, Field(description="The character's backstory, personality, and motivations.")] = None,
      background: Annotated[str | None, Field(description="Character background")] = None,
      alignment: Annotated[str | None, Field(description="Character alignment")] = None,
      hit_points_current: Annotated[int | None, Field(description="Current hit points", ge=0)] = None,
      hit_points_max: Annotated[int | None, Field(description="Maximum hit points", ge=1)] = None,
      temporary_hit_points: Annotated[int | None, Field(description="Temporary hit points", ge=0)] = None,
      armor_class: Annotated[int | None, Field(description="Armor class")] = None,
      inspiration: Annotated[bool | None, Field(description="Inspiration status")] = None,
      notes: Annotated[str | None, Field(description="Additional notes about the character")] = None,
      strength: Annotated[int | None, Field(description="Strength score", ge=1, le=30)] = None,
      dexterity: Annotated[int | None, Field(description="Dexterity score", ge=1, le=30)] = None,
      constitution: Annotated[int | None, Field(description="Constitution score", ge=1, le=30)] = None,
      intelligence: Annotated[int | None, Field(description="Intelligence score", ge=1, le=30)] = None,
      wisdom: Annotated[int | None, Field(description="Wisdom score", ge=1, le=30)] = None,
      charisma: Annotated[int | None, Field(description="Charisma score", ge=1, le=30)] = None,
  ) -> str:
      """Update a character's properties."""
      character = storage.get_character(name_or_id)
      if not character:
          return f"❌ Character '{name_or_id}' not found."
  
      updates = {k: v for k, v in locals().items() if v is not None and k not in ["name_or_id", "character"]}
      updated_fields = [f"{key.replace('_', ' ')}: {value}" for key, value in updates.items()]
  
      if not updates:
          return f"No updates provided for {character.name}."
  
      storage.update_character(str(character.id), **updates)
  
      return f"Updated {character.name}'s properties: {'; '.join(updated_fields)}."

• src/gamemaster_mcp/storage.py:246-275 (helper)

  Storage class method that performs the actual persistence of character updates to the campaign data file, handling attribute updates, name changes, and saving.

  def update_character(self, name_or_id: str, **kwargs) -> None:
      """Update a character's data."""
      if not self._current_campaign:
          raise ValueError("No current campaign")
  
      logger.info(f"📝 Attempting to update character '{name_or_id}' with data: {kwargs}")
      character = self._find_character(name_or_id)
      if not character:
          e = ValueError(f"❌ Character '{name_or_id}' not found!")
          logger.error(e)
          raise e
  
      original_name = character.name
      new_name = kwargs.get("name")
  
      for key, value in kwargs.items():
          if hasattr(character, key):
              logger.debug(f"📝 Updating character '{original_name}': {key} -> {value}")
              setattr(character, key, value)
  
      character.updated_at = datetime.now()
  
      if new_name and new_name != original_name:
          # If name changed, update the dictionary key
          logger.debug(f"🏷️ Character name changed from '{original_name}' to '{new_name}'. Updating dictionary key.")
          self._current_campaign.characters[new_name] = self._current_campaign.characters.pop(original_name)
  
      self._current_campaign.updated_at = datetime.now()
      self._save_campaign()
      logger.info(f"✅ Character '{new_name or original_name}' updated successfully.")