D&D MCP Server

Instructions

Implementation Reference

• src/gamemaster_mcp/main.py:416-430 (handler)

  The primary handler for the 'list_npcs' MCP tool. Decorated with @mcp.tool for automatic registration in FastMCP. Retrieves NPC list from storage, enriches with location info, and returns a formatted markdown list.

  @mcp.tool
  def list_npcs() -> str:
      """List all NPCs in the current campaign."""
      npcs = storage.list_npcs()
      if not npcs:
          return "No NPCs in the current campaign."
  
      npc_list = []
      for npc_name in npcs:
          npc = storage.get_npc(npc_name)
          if npc:
              location = f" ({npc.location})" if npc.location else ""
              npc_list.append(f"• {npc.name}{location}")
  
      return "**NPCs:**\n" + "\n".join(npc_list)

• src/gamemaster_mcp/storage.py:317-322 (helper)

  Helper method in DnDStorage class that returns the keys (names) of NPCs in the current campaign's npcs dictionary.

  def list_npcs(self) -> list[str]:
      """List all NPC names."""
      if not self._current_campaign:
          return []
      return list(self._current_campaign.npcs.keys())

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

  The @mcp.tool decorator registers the list_npcs function as an MCP tool in the FastMCP server.

  @mcp.tool