D&D MCP Server

Instructions

Implementation Reference

• src/gamemaster_mcp/main.py:742-770 (handler)

  The primary handler for the 'get_events' MCP tool. Decorated with @mcp.tool for automatic registration. Fetches events from storage (filtering by limit, type, or search), formats them into a markdown list, and returns as string.

  @mcp.tool
  def get_events(
      limit: Annotated[int | None, Field(description="Maximum number of events to return", ge=1)] = None,
      event_type: Annotated[Literal["combat", "roleplay", "exploration", "quest", "character", "world", "session"] | None, Field(description="Filter by event type")] = None,
      search: Annotated[str | None, Field(description="Search events by title/description")] = None,
  ) -> str:
      """Get events from the adventure log."""
      if search:
          events = storage.search_events(search)
      else:
          events = storage.get_events(limit=limit, event_type=event_type)
  
      if not events:
          return "No events found."
  
      event_list = []
      for event in events:
          timestamp = event.timestamp.strftime("%Y-%m-%d %H:%M")
          session_text = f" (Session {event.session_number})" if event.session_number else ""
          importance_stars = "★" * event.importance
  
          event_list.append(f"**{event.title}** [{event.event_type}] {importance_stars}")
          event_list.append(f"  {timestamp}{session_text}")
          event_list.append(f"  {event.description[:150]}{'...' if len(event.description) > 150 else ''}")
          if event.location:
              event_list.append(f"  📍 {event.location}")
          event_list.append("")
  
      return "**Adventure Log:**\n\n" + "\n".join(event_list)

• src/gamemaster_mcp/storage.py:424-437 (helper)

  Helper method on the Storage class that retrieves, filters by event_type, sorts by timestamp (newest first), limits, and returns list of AdventureEvent objects. Called by the main handler.

  def get_events(self, limit: int | None = None, event_type: str | None = None) -> list[AdventureEvent]:
      """Get adventure events, optionally filtered."""
      events = self._events
  
      if event_type:
          events = [e for e in events if e.event_type == event_type]
  
      # Sort by timestamp (newest first)
      events = sorted(events, key=lambda e: e.timestamp, reverse=True)
  
      if limit:
          events = events[:limit]
  
      return events

• src/gamemaster_mcp/main.py:744-747 (schema)

  Input schema definitions using Pydantic Field and typing.Literal for the tool parameters: limit (optional int >=1), event_type (optional specific literal strings), search (optional str).

      limit: Annotated[int | None, Field(description="Maximum number of events to return", ge=1)] = None,
      event_type: Annotated[Literal["combat", "roleplay", "exploration", "quest", "character", "world", "session"] | None, Field(description="Filter by event type")] = None,
      search: Annotated[str | None, Field(description="Search events by title/description")] = None,
  ) -> str: