Gamemaster MCP 🐉

一个全面的模型上下文协议MCP服务器，用于管理AI辅助的龙与地下城战役，基于**FastMCP 2.9.0+**构建。

Gamemaster MCP 🐉旨在成为DnD 5e的终极AI辅助地下城主，提供：

• 对于团队：一套全面的工具包，帮助用户更有效地运行战役。
• 对于单人玩家：一个完整的虚拟DnD体验，促进沉浸式单人游戏。
• 对于世界构建者：强大的工具，协助创建丰富、互联的游戏世界。

基于FastMCP构建的服务器提供了结构化数据模型和智能工具，以管理D&D战役的所有方面，并通过MCP客户端实现自然语言交互。

🚧 正在建设中 🚧

✨ 特性

🌍 战役管理

您D&D世界的基石。每个战役包含：

• 核心元数据：名称、描述、设定、DM姓名
• 角色：所有玩家角色及其表单
• NPC：您世界中的所有非玩家角色
• 地点：城市、地牢和兴趣点
• 任务：正在进行和已完成的故事线
• 游戏状态：当前会话、队伍位置、世界条件

所有数据都会自动保存，并可以在会话之间共享。

• 创建并管理多个战役
• 在不同战役之间无缝切换
• 跟踪战役元数据（名称、描述、DM、设定）

📑 角色管理

完整的D&D 5e角色表单，包括：

• 核心属性：带有自动计算修正值的能力分数
• 战斗统计：生命值、护甲等级、豁免投掷、抗力
• 装备：带有重量和价值追踪的装备
• 施法：准备好的法术、法术位和DC
• 进度：自动解锁特性的升级

角色随着您的游戏而发展——受到伤害、获得物品和升级。

• 完整的角色表单，带有D&D 5e统计数据
• 带有自动计算修正值的能力分数
• 生命值、护甲等级和战斗统计
• 装备和装备管理
• 施法支持

🧝 NPC管理

通过丰富的NPC使您的世界栩栩如生，包括：

• 描述：外貌、个性、语音笔记
• 关系：与其他角色或派系的联系
• 地点：他们居住和经常去的地方
• 秘密：隐藏的动机和知识
• 统计：如果需要，快速参考战斗

NPC可以链接到任务和地点，便于参考。

• 创建和跟踪非玩家角色
• 管理关系和地点
• 存储描述和笔记

🗺️ 地点/世界构建

创建沉浸式设置，包括：

• 详细描述：感官细节和地图
• 显著特征：地标、秘密、危险
• 连接：旅行路线的链接区域
• 居民：存在的NPC和怪物
• 传说：本地历史和传奇

随着队伍探索，地点会更新——添加发现的区域和改变的条件。

• 创建详细的地点（城市、地牢等）
• 跟踪人口、政府和显著特征
• 连接地点并管理地理

💎 任务管理

跟踪故事弧线和任务，包括：

• 目标：完成的明确步骤
• 状态跟踪：进行中/已完成/失败
• 给予者&奖励：关联的NPC和奖品
• 时间敏感性：可选的截止日期
• 分支路径：替代解决方案

任务进度会自动更新游戏状态和冒险日志。

• 创建具有目标和奖励的任务
• 跟踪任务状态和完成情况
• 将任务链接到NPC和地点

⚔️ 战斗管理

跟踪和运行动态战斗遭遇，包括：

• 先攻顺序：自动排序，手动覆盖
• 回合跟踪：当前行动者的高亮显示和回合提醒
• 状态管理：带有持续时间跟踪的状态效果
• 伤害/治疗：应用自动计算的生命值
• 敌人统计：怪物/NPC的快速参考

战斗数据流向：

• 角色表单（生命值、状态）

• 游戏状态（当前遭遇）

• 冒险日志（战斗事件）

• 先攻跟踪

• 回合制战斗流程

• 战斗遭遇规划

⏰ 会话管理

组织您的游戏会话，包括：

• 会话笔记：关键事件和决策
• 出席跟踪：哪些玩家在场
• 经验值奖励：跟踪角色进度
• 战利品分配：找到并认领的财宝
• 游戏日期：跟踪世界内的时间流逝

会话数据更新：

• 角色表单（经验值、物品）

• 游戏状态（当前会话编号）

• 冒险日志（会话总结）

• 会话笔记和总结

• 经验值和战利品跟踪

• 角色出席

🏕️ 冒险日志

您战役的活生生的历史：

• 事件类型：战斗、角色扮演、探索等
• 时间轴视图：按时间顺序的故事进展
• 可搜索：快速找到关键时刻
• 标签&重要性：突出主要情节点
• 会话链接：将事件链接到游戏会话

日志连接到：

• 任务（进度更新）

• 地点（事件发生的地方）

• NPC（谁参与了）

• 全面的事件记录

• 按事件类型分类（战斗、角色扮演、探索等）

• 可搜索和过滤

• 重要性评级

🎮 游戏状态跟踪

您世界的当前快照：

• 队伍状态：位置、资源、状态
• 活动任务：当前目标和进度
• 世界条件：天气、政治气候
• 时间跟踪：游戏内的日期和时间
• 战斗状态：当前遭遇详情

游戏状态连接所有其他模型：

• 来自角色动作的更新

• 驱动世界模拟

• 提供AI DM决策信息

• 当前位置和会话

• 队伍等级和资金

• 战斗状态

• 游戏内日期跟踪

🎲 实用工具

• 投骰子，带有优势/劣势
• 经验值计算
• D&D 5e机制支持

💾 安装

先决条件

• Python 3.12+
• uv（在系统PATH中可用）

用户安装

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-m- cp为您项目的绝对路径。

🎛️ 系统提示建议

为了最佳性能，使用一个系统提示，引导LLM充当知识渊博的地下城主助手。此提示应指导模型理解D&D战役管理的背景，并有效利用提供的工具。

📜 示例系统提示

您是一位大师级地下城主（DM）或地下城主助手，由Gamemaster MCP服务器驱动。您的主要职责是帮助用户使用一系列专门工具管理他们的所有D&D战役。您是一个有状态的实体，始终在一个当前活跃的战役中操作。

**核心原则：**

1. **战役中心**：所有数据——角色、NPC、任务、地点——都存储在一个单一的活跃`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. **讲故事**：虽然您的主要功能是数据管理，但要在D&D游戏的背景下表述您的响应。您不仅是数据库；您是战役世界的守护者。

**互动会话零：**

当用户想要开始新的战役时，启动一个互动的“会话零”。逐步引导他们完成设置过程，提问并使用工具协作构建世界。使用以下框架作为*宽松*框架：更重要的是跟随用户的提示。但是，请确保为每次工具调用建立必要的参数。

1. **建立战役：**
    * **您**：“欢迎来到冒险的世界！我们新的战役叫什么名字？”（等待用户输入）
    * **您**：“太棒了！‘战役名称’的中心主题或描述是什么？”（等待用户输入）
    * *然后，使用`create_campaign`与收集的信息。*

2. **组建队伍：**
    * **您**：“现在，让我们集结英雄们。队伍中有多少名玩家？”
    * *对于每名玩家，进行对话以创建他们的角色：*
    * **您**：“让我们创建第一个角色。他们的名字、种族和班级是什么？”
    * **您**：“很好。他们的能力分数（力量、敏捷等）是什么？”
    * *在收集每个英雄的核心细节后，使用`create_character`。*

3. **充实世界：**
    * **您**：“我们的故事从哪里开始？描述起点城镇或地点。”
    * *使用`create_location`。*
    * **您**：“队伍遇到的第一个人是谁？让我们创建一个NPC。”
    * *使用`create_npc`。*

4. **启动冒险：**
    * **您**：“随着世界设定完毕，队伍面临的第一个挑战或任务是什么？”
    * *使用`create_quest`。*
    * **您**：“会话零完成！我已经记录了您第一次会话的开始。您准备好开始了吗？”
    * *使用`add_session_note`。*

您的目标是成为地下城主不可或缺的伙伴，共同创建战役的基础，以便他们可以专注于讲述精彩的故事。

**进行中的战役指导：**

一旦战役开始，您的重点转向动态管理和叙事支持：

1. **动态世界**：根据玩家行为和工具输出动态更新`GameState`、`NPC`状态、`Location`详情和`Quest`进度。
2. **事件记录**：每个重要的互动、战斗回合、角色扮演遭遇或任务里程碑都应使用`add_event`记录，以维护全面的`AdventureLog`。
3. **主动DM支持**：预测DM的需求。如果角色受到伤害，建议`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 - 创建一个新的NPC
• get_npc - 获取NPC详情
• list_npcs - 列出所有NPC

地点管理

• 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 - 投骰子，带有D&D符号（例如，“1d20”，“3d6+2”）
• calculate_experience - 计算遭遇的经验值分布

💽 数据结构

Gamemaster 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模型字典，代表非玩家角色。NPC可以链接到Location模型。
  • locations：一个Location模型字典，定义战役世界中的地方。地点可以列出相关的NPC和与其他地点的连接。
  • quests：一个Quest模型字典，跟踪正在进行和已完成的任务。任务可以引用NPC作为给予者。
  • 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。这为理解过去的事件和叙述进展提供了历史记录。

🖥️ 开发

开发工作流

如果您想为项目做出贡献，设置略有