D&D MCP Server

Instructions

Implementation Reference

• src/gamemaster_mcp/main.py:519-539 (handler)

  The MCP tool handler for 'update_quest'. Handles input parameters (schema), retrieves quest, updates status via storage helper or directly appends completed objectives, and saves changes.

  @mcp.tool
  def update_quest(
      title: Annotated[str, Field(description="Quest title")],
      status: Annotated[Literal["active", "completed", "failed", "on_hold"] | None, Field(description="New quest status")] = None,
      completed_objective: Annotated[str | None, Field(description="Objective to mark as completed")] = None,
  ) -> str:
      """Update quest status or complete objectives."""
      quest = storage.get_quest(title)
      if not quest:
          return f"Quest '{title}' not found."
  
      if status:
          storage.update_quest_status(title, status)
  
      if completed_objective:
          if completed_objective in quest.objectives and completed_objective not in quest.completed_objectives:
              quest.completed_objectives.append(completed_objective)
              storage._save_campaign()  # Direct save since we modified the object
  
      return f"Updated quest '{title}'"

• src/gamemaster_mcp/models.py:303-315 (schema)

  Pydantic model for Quest data structure. Defines fields like status, objectives, and completed_objectives used in the update_quest tool logic.

  class Quest(BaseModel):
      """Quest or mission."""
      id: str = Field(default_factory=lambda: random(length=8))
      title: str
      description: str
      giver: str | None = None  # NPC who gave the quest
      status: str = "active"  # active, completed, failed, on_hold
      objectives: list[str] = Field(default_factory=list)
      completed_objectives: list[str] = Field(default_factory=list)
      reward: str | None = None
      notes: str = ""
      created_at: datetime = Field(default_factory=datetime.now)

• src/gamemaster_mcp/storage.py:361-368 (helper)

  Storage layer helper method that updates the status field on a Quest object and persists the campaign changes to disk.

  def update_quest_status(self, title: str, status: str) -> None:
      """Update a quest's status."""
      quest = self.get_quest(title)
      if quest:
          quest.status = status
          self._current_campaign.updated_at = datetime.now()  # type: ignore
          self._save_campaign()

• src/gamemaster_mcp/main.py:519-519 (registration)

  FastMCP decorator that registers the update_quest function as a tool.

  @mcp.tool