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许可证。