D&D MCP Server

Instructions

Implementation Reference

• src/gamemaster_mcp/main.py:716-740 (handler)

  The MCP tool handler for 'add_event' decorated with @mcp.tool (registration). Defines input schema via Annotated parameters with descriptions and validations. Constructs AdventureEvent, calls storage to persist, returns confirmation.

  @mcp.tool
  def add_event(
      event_type: Annotated[Literal["combat", "roleplay", "exploration", "quest", "character", "world", "session"], Field(description="Type of event")],
      title: Annotated[str, Field(description="Event title")],
      description: Annotated[str, Field(description="Event description")],
      session_number: Annotated[int | None, Field(description="Session number", ge=1)] = None,
      characters_involved: Annotated[list[str] | None, Field(description="Characters involved in the event")] = None,
      location: Annotated[str | None, Field(description="Location where event occurred")] = None,
      importance: Annotated[int, Field(description="Event importance (1-5)", ge=1, le=5)] = 3,
      tags: Annotated[list[str] | None, Field(description="Tags for categorizing the event")] = None,
  ) -> str:
      """Add an event to the adventure log."""
      event = AdventureEvent(
          event_type=EventType(event_type),
          title=title,
          description=description,
          session_number=session_number,
          characters_involved=characters_involved or [],
          location=location,
          importance=importance,
          tags=tags or []
      )
  
      storage.add_event(event)
      return f"Added {event_type.lower} event: '{event.title}'"

• src/gamemaster_mcp/models.py:405-417 (schema)

  Pydantic BaseModel schema for AdventureEvent used by the tool for data validation and serialization.

  class AdventureEvent(BaseModel):
      """Individual event in the adventure log."""
      id: str = Field(default_factory=lambda: random(length=8))
      event_type: EventType
      title: str
      description: str
      timestamp: datetime = Field(default_factory=datetime.now)
      session_number: int | None = None
      characters_involved: list[str] = Field(default_factory=list)
      location: str | None = None
      tags: list[str] = Field(default_factory=list)
      importance: int = Field(ge=1, le=5, default=3)  # 1=minor, 5=major

• src/gamemaster_mcp/storage.py:417-422 (helper)

  Storage class helper method that appends the event to the internal list and saves to persistent storage.

  def add_event(self, event: AdventureEvent) -> None:
      """Add an event to the adventure log."""
      logger.info(f"➕ Adding event: '{event.title}' ({event.event_type})")
      self._events.append(event)
      self._save_events()
      logger.debug("✅ Event added and log saved.")