D&D MCP Server

Instructions

Implementation Reference

• src/gamemaster_mcp/main.py:672-696 (handler)

  MCP tool handler decorated with @mcp.tool. Validates inputs using Pydantic Annotated Fields, constructs a SessionNote instance, persists it using storage, and returns a confirmation message.

  @mcp.tool
  def add_session_note(
      session_number: Annotated[int, Field(description="Session number", ge=1)],
      summary: Annotated[str, Field(description="Session summary")],
      title: Annotated[str | None, Field(description="Session title")] = None,
      events: Annotated[list[str] | None, Field(description="Key events that occurred")] = None,
      characters_present: Annotated[list[str] | None, Field(description="Characters present in session")] = None,
      experience_gained: Annotated[int | None, Field(description="Experience points gained", ge=0)] = None,
      treasure_found: Annotated[list[str] | None, Field(description="Treasure or items found")] = None,
      notes: Annotated[str, Field(description="Additional notes")] = "",
  ) -> str:
      """Add notes for a game session."""
      session_note = SessionNote(
          session_number=session_number,
          title=title,
          summary=summary,
          events=events or [],
          characters_present=characters_present or [],
          experience_gained=experience_gained,
          treasure_found=treasure_found or [],
          notes=notes
      )
  
      storage.add_session_note(session_note)
      return f"Added session note for Session {session_note.session_number}"

• src/gamemaster_mcp/models.py:330-342 (schema)

  Pydantic BaseModel defining the structure and validation for SessionNote objects used by the tool.

  class SessionNote(BaseModel):
      """Session notes and summary."""
      id: str = Field(default_factory=lambda: random(length=8))
      session_number: int
      date: datetime = Field(default_factory=datetime.now)
      title: str | None = None
      summary: str
      events: list[str] = Field(default_factory=list)
      characters_present: list[str] = Field(default_factory=list)
      experience_gained: int | None = None
      treasure_found: list[str] = Field(default_factory=list)
      notes: str = ""

• src/gamemaster_mcp/storage.py:401-408 (helper)

  Helper method in DnDStorage class that appends the SessionNote to the current campaign's sessions list and persists the changes to disk.

  def add_session_note(self, session_note: SessionNote) -> None:
      """Add a session note."""
      if not self._current_campaign:
          raise ValueError("No current campaign")
  
      self._current_campaign.sessions.append(session_note)
      self._current_campaign.updated_at = datetime.now()
      self._save_campaign()