JinDaGe - gamemaster-mcp MCP Details

article

README

🚀 游戏大师MCP 🐉

游戏大师MCP 🐉 是一款全面的模型上下文协议MCP 服务器，专为管理人工智能辅助的《龙与地下城》（Dungeons & Dragons）游戏活动而设计，基于 FastMCP 2.9.0+ 构建。

它旨在成为《龙与地下城5e版》（DnD 5e）中终极的人工智能辅助地下城主，提供以下功能：

团队玩家：一套全面的工具包，帮助用户更高效地开展游戏活动。
单人玩家：完整的虚拟《龙与地下城》体验，助力沉浸式单人游戏。
世界构建者：强大的工具，协助创建丰富、相互关联的游戏世界。

该服务器基于FastMCP构建，提供结构化数据模型和智能工具，以管理《龙与地下城》游戏活动的各个方面，同时支持通过MCP客户端进行自然语言交互。

🚧 项目建设中 🚧

✨ 主要特性

🌍 活动管理

这是你的《龙与地下城》世界的基础。每个游戏活动包含：

核心元数据：名称、描述、背景设定、地下城主姓名
角色：所有玩家角色及其角色表
非玩家角色（NPC）：游戏世界中的每个非玩家角色
地点：城市、地下城和名胜古迹
任务：正在进行和已完成的故事情节
游戏状态：当前游戏会话、团队位置、世界状况

所有数据会自动保存，并可在不同游戏会话之间共享。

创建和管理多个游戏活动
无缝切换不同的游戏活动
跟踪游戏活动的元数据（名称、描述、地下城主、背景设定）

📑 角色管理

完整的《龙与地下城5e版》角色表，包含：

核心属性：能力值及自动计算的修正值
战斗统计：生命值、护甲等级、豁免检定、抗性
物品栏：可跟踪装备的重量和价值
法术施放：已准备的法术、法术位和法术难度等级
升级：升级时自动解锁新特性

角色会随着游戏进程而成长，承受伤害、获得物品并提升等级。

具有《龙与地下城5e版》统计数据的完整角色表
能力值及自动计算的修正值
生命值、护甲等级和战斗统计数据
物品栏和装备管理
法术施放支持

🧝 NPC管理

通过丰富的NPC让你的游戏世界栩栩如生，这些NPC具有：

描述：外貌、性格、语音备注
关系：与其他角色/阵营的联系
地点：他们居住和常去的地方
秘密：隐藏的动机和知识
统计数据：必要时可快速参考战斗数据

NPC可以与任务和地点关联，方便查询。

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

🗺️ 地点/世界构建

通过以下内容创建沉浸式的游戏场景：

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

地点会随着团队探索而更新，添加新发现的区域并改变状况。

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

💎 任务管理

跟踪故事情节和任务，包括：

目标：明确的完成步骤
状态跟踪：进行中/已完成/失败
任务发布者与奖励：相关的NPC和奖品
时间敏感性：可选的截止日期
分支路径：不同的解决方案

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

创建带有目标和奖励的任务
跟踪任务状态和完成情况
将任务与NPC和地点关联

⚔️ 战斗管理

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

先攻顺序：自动排序，支持手动调整
回合跟踪：突出显示当前行动者并提供回合提醒
状态管理：跟踪状态效果及其持续时间
伤害/治疗：应用伤害和治疗，自动计算生命值
敌人统计数据：快速参考怪物/NPC的战斗数据

战斗数据会流向：

角色表（生命值、状态）
游戏状态（当前战斗遭遇）
冒险日志（战斗事件）
先攻顺序跟踪
回合制战斗流程
战斗遭遇规划

⏰ 会话管理

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

会话笔记：关键事件和决策
出勤跟踪：记录参与的玩家
经验值奖励：跟踪角色升级进度
战利品分配：找到并认领的宝藏
游戏日期：跟踪游戏世界中的时间流逝

会话数据会更新：

角色表（经验值、物品）
游戏状态（当前会话编号）
冒险日志（会话总结）
会话笔记和总结
经验值和宝藏跟踪
角色出勤记录

🏕️ 冒险日志

这是你游戏活动的鲜活历史：

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

日志与以下内容关联：

任务（进度更新）
地点（事件发生的地点）
NPC（参与的角色）
全面的事件记录
按事件类型分类（战斗、角色扮演、探索等）
可搜索和过滤
重要性评级

🎮 游戏状态跟踪

这是你游戏世界的当前快照：

团队状态：位置、资源、状态
进行中的任务：当前目标和进度
世界状况：天气、政治环境
时间跟踪：游戏内的日期和时间
战斗状态：当前战斗遭遇的详细信息

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

根据角色行动更新
驱动世界模拟
为人工智能地下城主的决策提供信息
当前位置和会话
团队等级和资金
战斗状态
游戏内日期跟踪

🎲 实用工具

支持优势/劣势的骰子投掷
经验值计算
《龙与地下城5e版》机制支持

📦 安装指南

前提条件

Python 3.12+
uv（需添加到系统环境变量的PATH中）

用户安装步骤

克隆仓库：

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

创建虚拟环境并安装依赖：

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. **以活动为中心**：所有数据（角色、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. **成为故事讲述者**：虽然你的主要功能是数据管理，但要在《龙与地下城》游戏的上下文中组织你的回复。你不仅仅是一个数据库，更是游戏活动世界的守护者。

**交互式零号会话**：
当用户想要开始一个新的游戏活动时，发起一个交互式的“零号会话”。逐步引导他们完成设置过程，询问问题并使用工具共同构建游戏世界。使用以下框架作为一个 *大致* 的参考：更重要的是遵循用户的提示。但要确保为每个工具调用建立必要的参数。
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. **主动的地下城主支持**：预测地下城主的需求。如果一个角色受到伤害，建议使用 `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 - 使用《龙与地下城》的符号表示法掷骰子（例如：“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 模型的字典，代表非玩家角色。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。这提供了一个历史记录，用于理解过去的事件和故事情节的进展。

🖥️ 开发

开发工作流程

如果你想为项目做出贡献，设置过程略有不同。

按照用户安装步骤 克隆仓库并设置虚拟环境。
以可编辑模式安装项目，并包含开发依赖：

uv pip install -e .[dev]

这样安装项目后，你的代码更改将立即生效，无需重新安装。同时，它还会安装用于测试和代码检查的工具。

运行测试

要运行测试套件，请使用以下命令：

uv run pytest

📄 许可证

本项目采用 MIT 许可证。