Gamemaster MCP

🚀 遊戲大師MCP 🐉

遊戲大師MCP 🐉 是一個全面的 模型上下文協議MCP 服務器，用於管理人工智能輔助的《龍與地下城》（Dungeons & Dragons）遊戲活動。它基於 FastMCP 2.9.0+ 構建。

該項目旨在成為《龍與地下城5e版》（DnD 5e）中終極的人工智能輔助地下城主，具備以下功能：

• 團隊玩家：提供一套全面的工具包，幫助用戶更有效地開展遊戲活動。
• 單人玩家：提供完整的虛擬《龍與地下城》體驗，便於沉浸式的單人遊戲。
• 世界構建者：提供強大的工具，協助創建豐富、相互關聯的遊戲世界。

該服務器基於FastMCP構建，提供結構化的數據模型和智能工具，用於管理《龍與地下城》遊戲活動的各個方面，同時支持通過MCP客戶端進行自然語言交互。

🚧 項目建設中 🚧

✨ 主要特性

🌍 活動管理

這是你的《龍與地下城》世界的基礎。每個遊戲活動包含：

• 核心元數據：名稱、描述、背景設定、地下城主姓名。
• 角色：所有玩家角色及其角色表。
• 非玩家角色（NPC）：遊戲世界中的每個非玩家角色。
• 地點：城市、地下城和名勝古蹟。
• 任務：正在進行和已完成的故事情節。
• 遊戲狀態：當前遊戲會話、團隊位置、世界狀況。

所有數據會自動保存，並且可以在不同會話之間共享。

• 創建和管理多個遊戲活動。
• 無縫切換遊戲活動。
• 跟蹤遊戲活動的元數據（名稱、描述、地下城主、背景設定）。

📑 角色管理

提供完整的《龍與地下城5e版》角色表，包含：

• 核心屬性：能力值及自動計算的修正值。
• 戰鬥統計：生命值、護甲等級、豁免檢定、抗性。
• 物品欄：跟蹤裝備的重量和價值。
• 法術施法：準備好的法術、法術位和法術難度等級。
• 升級：升級時自動解鎖特性。

角色會隨著遊戲進程而發展，例如承受傷害、獲得物品和升級。

• 提供完整的《龍與地下城5e版》角色統計信息。
• 能力值自動計算修正值。
• 生命值、護甲等級和戰鬥統計。
• 物品欄和裝備管理。
• 法術施法支持。

🧝 非玩家角色（NPC）管理

通過豐富的非玩家角色讓你的遊戲世界栩栩如生，這些角色具有以下特點：

• 描述：外貌、性格、語音備註。
• 關係：與其他角色/陣營的聯繫。
• 地點：他們居住和常去的地方。
• 秘密：隱藏的動機和知識。
• 統計信息：必要時可快速參考戰鬥數據。

非玩家角色可以與任務和地點關聯，方便查詢。

• 創建和跟蹤非玩家角色。
• 管理關係和位置。
• 存儲描述和備註。

🗺️ 地點/世界構建

創建沉浸式的遊戲場景，包括：

• 詳細描述：感官細節和地圖。
• 顯著特徵：地標、秘密、危險。
• 連接：用於旅行路線的關聯區域。
• 居民：存在的非玩家角色和怪物。
• 傳說：當地的歷史和傳說。

地點會隨著團隊探索而更新，例如添加新發現的區域和改變狀況。

• 創建詳細的地點（城市、地下城等）。
• 跟蹤人口、政府和顯著特徵。
• 連接地點並管理地理信息。

💎 任務管理

跟蹤故事情節和任務，包括：

• 目標：明確的完成步驟。
• 狀態跟蹤：進行中/已完成/失敗。
• 發佈者與獎勵：關聯的非玩家角色和獎品。
• 時間敏感性：可選的截止日期。
• 分支路徑：不同的解決方案。

任務進度會自動更新遊戲狀態和冒險日誌。

• 創建帶有目標和獎勵的任務。
• 跟蹤任務狀態和完成情況。
• 將任務與非玩家角色和地點關聯。

⚔️ 戰鬥管理

跟蹤和進行動態的戰鬥遭遇，包括：

• 先攻順序：自動排序，支持手動調整。
• 回合跟蹤：突出顯示當前行動者並提供回合提醒。
• 狀態管理：跟蹤狀態效果及其持續時間。
• 傷害/治療：應用傷害和治療，自動計算生命值。
• 敵人統計：快速參考怪物/非玩家角色的統計信息。

戰鬥數據會同步到：

• 角色表（生命值、狀態）。
• 遊戲狀態（當前戰鬥遭遇）。
• 冒險日誌（戰鬥事件）。
• 先攻跟蹤。
• 回合制戰鬥流程。
• 戰鬥遭遇規劃。

⏰ 會話管理

組織遊戲會話，包括：

• 會話筆記：關鍵事件和決策。
• 出勤跟蹤：記錄出席的玩家。
• 經驗值獎勵：跟蹤角色升級。
• 戰利品分配：找到並認領的寶藏。
• 遊戲日期：跟蹤遊戲內的時間流逝。

會話數據會更新：

• 角色表（經驗值、物品）。
• 遊戲狀態（當前會話編號）。
• 冒險日誌（會話摘要）。
• 會話筆記和摘要。
• 經驗值和寶藏跟蹤。
• 角色出勤記錄。

🏕️ 冒險日誌

記錄遊戲活動的實時歷史，包括：

• 事件類型：戰鬥、角色扮演、探索等。
• 時間線視圖：按時間順序排列的故事情節。
• 可搜索：快速查找關鍵時刻。
• 標籤與重要性：突出主要情節要點。
• 會話關聯：將事件與遊戲會話關聯。

日誌與以下內容關聯：

• 任務（進度更新）。
• 地點（事件發生地點）。
• 非玩家角色（參與的角色）。
• 全面的事件記錄。
• 按事件類型分類（戰鬥、角色扮演、探索等）。
• 可搜索和過濾。
• 重要性評級。

🎮 遊戲狀態跟蹤

顯示遊戲世界的當前快照，包括：

• 團隊狀態：位置、資源、狀態。
• 活躍任務：當前目標和進度。
• 世界狀況：天氣、政治氣候。
• 時間跟蹤：遊戲內的日期和時間。
• 戰鬥狀態：當前戰鬥遭遇的詳細信息。

遊戲狀態與所有其他模型關聯：

• 根據角色行動更新。
• 驅動世界模擬。
• 為人工智能地下城主的決策提供信息。
• 當前位置和會話。
• 團隊等級和資金。
• 戰鬥狀態。
• 遊戲內日期跟蹤。

🎲 實用工具

• 支持優勢/劣勢的骰子投擲。
• 經驗值計算。
• 《龍與地下城5e版》機制支持。

📦 安裝指南

前提條件

• Python 3.12+
• uv（需添加到系統環境變量中）

用戶安裝步驟

1. 克隆倉庫：

git clone https://github.com/study-flamingo/gamemaster-mcp.git
cd gamemaster-mcp

2. 創建虛擬環境並安裝依賴：

uv venv
uv pip install .

🚀 快速開始

從命令行啟動

若要直接運行服務器，首先激活虛擬環境：

# 在 macOS/Linux 系統上
source .venv/bin/activate

# 在 Windows 系統上
.venv\Scripts\activate

然後，運行可執行文件：

gamemaster-mcp

或者，使用 uv 運行腳本，無需激活環境：

uv run gamemaster-mcp

使用MCP客戶端（如Claude Desktop）

配置你的MCP客戶端，使用 uv 運行服務器。你只需提供項目文件夾的路徑作為工作目錄。

{
  "mcpServers": {
    "gamemaster-mcp": {
      "command": "uv",
      "args": [
        "run",
        "gamemaster-mcp"
      ],
      "cwd": "C:\\path\\to\\your\\gamemaster-mcp"
    }
  }
}

注意：請將 C:\\path\\to\\your\\gamemaster-mcp 替換為項目目錄的絕對路徑。

🎛️ 系統提示建議

為獲得最佳性能，建議使用系統提示來引導大語言模型（LLM）扮演知識淵博的地下城主助手。該提示應幫助模型理解《龍與地下城》遊戲活動管理的上下文，並有效利用提供的工具。

📜 系統提示示例

你是一位資深的地下城主（DM）或地下城主助手，由遊戲大師MCP服務器提供支持。你的主要職責是幫助用戶利用一系列豐富的專業工具管理《龍與地下城》遊戲活動的各個方面。你是一個有狀態的實體，始終在單個當前活躍的遊戲活動中運行。

**核心原則**：
1. **以活動為中心**：所有數據（角色、非玩家角色、任務、地點）都存儲在單個活躍的 `Campaign` 中。始終了解當前遊戲活動的上下文。如果用戶的請求似乎引用了不同的遊戲活動，請使用 `list_campaigns` 和 `load_campaign` 工具切換上下文。
2. **結構化數據**：你使用結構化數據模型（`Character`、`NPC`、`Quest`、`Location` 等）。在創建或更新這些實體時，儘量提供詳細信息。如果用戶的請求模糊，請詢問具體信息（例如，“角色的職業和種族是什麼？他們的能力值是多少？”）。
3. **主動協助**：不要只執行單個命令。通過鏈式調用工具來滿足複雜的用戶請求。例如，要“將新角色添加到團隊中”，你應該使用 `create_character`，然後可能使用 `add_item_to_character` 為他們提供初始裝備。
4. **信息收集**：在採取行動之前，使用 `list_` 和 `get_` 工具瞭解當前狀態。例如，在添加任務之前，你可以使用 `list_npcs` 查看誰可以作為任務發佈者。
5. **狀態管理**：使用 `get_game_state` 和 `update_game_state` 工具跟蹤團隊的當前位置、遊戲內日期和戰鬥狀態。
6. **成為故事講述者**：雖然你的主要功能是數據管理，但要在《龍與地下城》遊戲的背景下組織你的回覆。你不僅僅是一個數據庫，更是遊戲活動世界的守護者。

**交互式零會話**：
當用戶想要開始新的遊戲活動時，啟動交互式的“零會話”。一步一步地引導他們完成設置過程，詢問問題並使用工具共同構建遊戲世界。使用以下框架作為參考，但更重要的是遵循用戶的提示。確保為每個工具調用設置必要的參數。
1. **創建遊戲活動**：
    - **你**：“歡迎來到冒險世界！我們的新遊戲活動叫什麼名字？”（等待用戶輸入）
    - **你**：“太棒了！‘遊戲活動名稱’的核心主題或描述是什麼？”（等待用戶輸入）
    - 然後，使用 `create_campaign` 工具並傳入收集到的信息。
2. **組建團隊**：
    - **你**：“現在，讓我們召集我們的英雄。團隊中有多少玩家？”
    - 對於每個玩家，進行對話以創建他們的角色：
    - **你**：“讓我們創建第一個角色。他們的名字、種族和職業是什麼？”
    - **你**：“很好。他們的能力值（力量、敏捷等）是多少？”
    - 在收集每個英雄的核心細節後，使用 `create_character` 工具。
3. **完善世界**：
    - **你**：“我們的故事從哪裡開始？描述一下起始城鎮或地點。”
    - 使用 `create_location` 工具。
    - **你**：“團隊遇到的第一個人是誰？讓我們創建一個非玩家角色。”
    - 使用 `create_npc` 工具。
4. **開啟冒險**：
    - **你**：“我們的世界已經搭建好，團隊面臨的第一個挑戰或任務是什麼？”
    - 使用 `create_quest` 工具。
    - **你**：“零會話完成！我已經記錄了第一次遊戲會話的開始。你準備好開始了嗎？”
    - 使用 `add_session_note` 工具。

你的目標是成為地下城主不可或缺的合作伙伴，共同創建遊戲活動的基礎，讓他們能夠專注於講述精彩的故事。

**遊戲活動進行中的指導**：
一旦遊戲活動開始，你的重點將轉移到動態管理和敘事支持：
1. **動態世界**：根據玩家的行動和工具輸出，動態更新 `GameState`、`NPC` 狀態、`Location` 細節和 `Quest` 進度。
2. **事件記錄**：使用 `add_event` 工具記錄每個重要的交互、戰鬥回合、角色扮演遭遇或任務里程碑，以維護全面的 `AdventureLog`。
3. **主動支持地下城主**：預測地下城主的需求。如果角色受到傷害，建議使用 `update_character_hp` 工具。如果他們進入新區域，提供 `get_location` 詳細信息。
4. **敘事連貫性**：保持敘事的一致性。參考 `AdventureLog` 或 `SessionNotes` 中的過去事件，豐富描述並確保連續性。
5. **挑戰與後果**：當玩家嘗試行動時，考慮潛在的結果，並使用適當的工具反映成功、失敗或部分成功，包括更新角色統計信息或遊戲狀態。
6. **工具驅動的回覆**：圍繞工具的成功執行來組織你的敘事回覆。例如，不要說“角色的生命值現在是15”，而是說“你成功治癒了 [角色名稱]，他們的生命值現在是15”。

📚 詳細文檔

可用工具（25+ 個FastMCP工具）

遊戲活動管理

• create_campaign - 創建新的遊戲活動。
• get_campaign_info - 獲取當前遊戲活動的信息。
• list_campaigns - 列出所有可用的遊戲活動。
• load_campaign - 切換到不同的遊戲活動。

角色管理

• create_character - 創建新的玩家角色。
• get_character - 獲取角色表詳細信息。
• update_character - 更新角色的屬性（名稱、統計信息、生命值等）。
• bulk_update_characters - 一次性更新多個角色（例如，對所有角色應用傷害）。
• add_item_to_character - 將物品添加到角色的物品欄。
• list_characters - 列出所有角色。

非玩家角色（NPC）管理

• create_npc - 創建新的非玩家角色。
• get_npc - 獲取非玩家角色的詳細信息。
• list_npcs - 列出所有非玩家角色。

地點管理

• create_location - 創建新的地點。
• get_location - 獲取地點的詳細信息。
• list_locations - 列出所有地點。

任務管理

• create_quest - 創建新的任務。
• update_quest - 更新任務狀態或目標。
• list_quests - 列出任務（可根據狀態過濾）。

遊戲狀態管理

• update_game_state - 更新當前遊戲狀態。
• get_game_state - 獲取當前遊戲狀態。

戰鬥管理

• start_combat - 初始化戰鬥並確定先攻順序。
• end_combat - 結束戰鬥遭遇。
• next_turn - 進入下一個參與者的回合。

會話管理

• add_session_note - 添加會話筆記和摘要。
• get_sessions - 獲取所有會話筆記。

冒險日誌

• add_event - 將事件添加到冒險日誌。
• get_events - 獲取事件（支持過濾和搜索）。

實用工具

• roll_dice - 使用《龍與地下城》符號進行骰子投擲（例如，“1d20”，“3d6+2”）。
• calculate_experience - 計算遭遇的經驗值分配。

🔧 技術細節

💽 數據結構

遊戲大師MCP服務器圍繞中央 Campaign 模型組織所有遊戲活動數據，該模型作為整個遊戲世界的主要容器。這種設計確保了數據結構的一致性和互聯性，便於管理和與各種遊戲元素進行交互。

系統基於分層數據結構構建，以 Campaign 模型為核心。所有其他模型都與活躍的遊戲活動相關，如下所示：

graph TD
    A[Campaign] --> B[GameState]
    A --> C[Character]
    A --> D[NPC]
    A --> E[Location]
    A --> F[Quest]
    A --> G[CombatEncounter]
    A --> H[SessionNote]
    B --> I[AdventureEvent]
    
    C --> J[Item]
    C --> K[Spell]
    C --> L[AbilityScore]
    C --> M[CharacterClass]
    C --> N[Race]
    
    style A fill:#f9f,stroke:#333,stroke-width:4px

以下是 src/gamemaster_mcp/models.py 中核心數據模型的交互方式：

• Campaign：基礎模型，封裝了所有與遊戲活動相關的數據，包括：
  • characters：一個包含 Character 模型的字典，代表玩家角色。每個 Character 是一個複雜的模型，由 CharacterClass、Race、AbilityScore（用於核心統計）、Item（用於物品欄和裝備）和 Spell（用於已知法術）組成。
  • npcs：一個包含 NPC 模型的字典，代表非玩家角色。非玩家角色可以與 Location 模型關聯。
  • locations：一個包含 Location 模型的字典，定義了遊戲活動世界中的地點。地點可以列出關聯的非玩家角色和與其他地點的連接。
  • quests：一個包含 Quest 模型的字典，跟蹤正在進行和已完成的任務。任務可以引用非玩家角色作為發佈者。
  • encounters：一個包含 CombatEncounter 模型的字典，詳細描述計劃或正在進行的戰鬥場景。戰鬥遭遇可以與特定地點關聯。
  • sessions：一個包含 SessionNote 模型的列表，提供每個遊戲會話的摘要和詳細信息。
  • game_state：一個單一的 GameState 模型，捕獲遊戲活動的動態實時條件，如當前位置、活躍任務和團隊資金。該模型對於理解遊戲的即時上下文至關重要。
• GameState：雖然是 Campaign 的一部分，但 GameState 在反映遊戲世界的當前狀態方面起著關鍵作用。它影響並受其他模型的影響：
  • current_location 可以指向一個 Location 模型。
  • active_quests 引用 Quest 的標題。
  • Character 狀態（例如，hit_points_current）或 Quest 狀態（active、completed）的變化直接影響 GameState。
• AdventureEvent：該模型用於記錄遊戲活動中的重要事件。雖然不直接嵌套在 Campaign 中（全局存儲），但 AdventureEvent 實例通常引用 Campaign 數據中的元素，如 characters_involved 和 location。這提供了一個歷史記錄，用於理解過去的事件和故事情節的發展。

🖥️ 開發

開發工作流程

如果你想為項目做出貢獻，設置過程略有不同。

1. 遵循用戶安裝步驟：克隆倉庫並設置虛擬環境。
2. 以可編輯模式安裝開發依賴：

uv pip install -e .[dev]

這將以可編輯模式安裝項目，使你的代碼更改無需重新安裝即可立即生效。同時，它還會安裝用於測試和代碼檢查的工具。

運行測試

要運行測試套件，請使用以下命令：

uv run pytest

📄 許可證

本項目採用MIT許可證。