D&D MCP Server

Instructions

Implementation Reference

• src/gamemaster_mcp/main.py:121-164 (handler)

  Handler function for 'create_character' tool. Includes registration via @mcp.tool decorator, input schema via Annotated Fields, core logic to build Character model from params, and persistence via storage.
  @mcp.tool def create_character( name: Annotated[str, Field(description="Character name")], character_class: Annotated[str, Field(description="Character class")], class_level: Annotated[int, Field(description="Class level", ge=1, le=20)], race: Annotated[str, Field(description="Character race")], 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, strength: Annotated[int, Field(description="Strength score", ge=1, le=30)] = 10, dexterity: Annotated[int, Field(description="Dexterity score", ge=1, le=30)] = 10, constitution: Annotated[int, Field(description="Constitution score", ge=1, le=30)] = 10, intelligence: Annotated[int, Field(description="Intelligence score", ge=1, le=30)] = 10, wisdom: Annotated[int, Field(description="Wisdom score", ge=1, le=30)] = 10, charisma: Annotated[int, Field(description="Charisma score", ge=1, le=30)] = 10, ) -> str: """Create a new player character.""" # Build ability scores abilities = { "strength": AbilityScore(score=strength), "dexterity": AbilityScore(score=dexterity), "constitution": AbilityScore(score=constitution), "intelligence": AbilityScore(score=intelligence), "wisdom": AbilityScore(score=wisdom), "charisma": AbilityScore(score=charisma), } character = Character( name=name, player_name=player_name, character_class=CharacterClass(name=character_class, level=class_level), race=Race(name=race), background=background, alignment=alignment, abilities=abilities, description=description, bio=bio, ) storage.add_character(character) return f"Created character '{character.name}' (Level {character.character_class.level} {character.race.name} {character.character_class.name})"
• src/gamemaster_mcp/models.py:207-272 (schema)

  Pydantic model for Character used in create_character tool implementation, defining the data structure persisted by the tool.
  class Character(BaseModel): """Complete character sheet.""" # Basic Info id: str = Field(default_factory=lambda: random(length=8)) name: str player_name: str | None = None character_class: CharacterClass race: Race background: str | None = None alignment: str | None = None description: str | None = None # A brief description of the character's appearance and demeanor. bio: str | None = None # The character's backstory, personality, and motivations. # Core Stats abilities: dict[str, AbilityScore] = Field( default_factory=lambda: { "strength": AbilityScore(score=10), "dexterity": AbilityScore(score=10), "constitution": AbilityScore(score=10), "intelligence": AbilityScore(score=10), "wisdom": AbilityScore(score=10), "charisma": AbilityScore(score=10), } ) # Combat Stats armor_class: int = 10 hit_points_max: int = 1 hit_points_current: int = 1 temporary_hit_points: int = 0 hit_dice_remaining: str = "1d8" death_saves_success: int = Field(ge=0, le=3, default=0) death_saves_failure: int = Field(ge=0, le=3, default=0) # Skills & Proficiencies proficiency_bonus: int = 2 skill_proficiencies: list[str] = Field(default_factory=list) saving_throw_proficiencies: list[str] = Field(default_factory=list) # Equipment inventory: list[Item] = Field(default_factory=list) equipment: dict[str, Item | None] = Field( default_factory=lambda: { "weapon_main": None, "weapon_off": None, "armor": None, "shield": None, } ) # Spellcasting spellcasting_ability: str | None = None spell_slots: dict[int, int] = Field(default_factory=dict) # level: max_slots spell_slots_used: dict[int, int] = Field(default_factory=dict) # level: used_slots spells_known: list[Spell] = Field(default_factory=list) # Character Features features_and_traits: list[str] = Field(default_factory=list) languages: list[str] = Field(default_factory=list) # Misc inspiration: bool = False notes: str = "" created_at: datetime = Field(default_factory=datetime.now) updated_at: datetime = Field(default_factory=datetime.now)