游戏大师MCP🐉
全面 模型上下文协议MCP 用于管理人工智能辅助的龙与地下城战役的服务器，由 FastMCP 2.9.0+
游戏大师MCP🐉 旨在成为DnD5e的终极人工智能辅助地牢大师，提供：
- 对于团体：一个全面的工具包，帮助用户更有效地开展活动
- 对于单人玩家：一个完整的虚拟DnD体验，有助于沉浸式独奏
- 对于Worldbuilders：强大的工具，可帮助创建丰富、互联的游戏世界
该服务器基于FastMCP构建，提供结构化数据模型和智能工具来管理D&D活动的各个方面，同时通过MCP客户端实现自然语言交互。
🚧 施工中🚧
✨ 特性
🌍 活动管理
你的D&D世界的基础。每个活动包含：
- 核心元数据：名称、描述、设置、DM名称
- 角色：所有玩家角色及其床单
- 前体细胞：你世界中的每个非玩家角色
- 位置：城市、地牢和景点
- 任务：活跃且完整的故事情节
- 游戏状态：本届会议、聚会地点、世界条件
所有数据都会自动保存，并可在会话之间共享。
- 创建和管理多个活动
- 在活动之间无缝切换
- 跟踪活动元数据（名称、描述、DM、设置）
📑 角色管理
完整的D&D 5e字符表，包括：
- 核心属性：带有自动计算修饰词的能力得分
- 战斗统计：HP、AC、节能、电阻
- 库存：具有重量和价值跟踪功能的设备
- 施法能力：准备好的法术、插槽和DC
- 进展：具有自动解锁功能的升级
角色会随着你的游戏而进化——受到伤害、获得物品和升级。
- 包含D&D 5e统计数据的完整角色表
- 具有自动修改计算功能的能力得分
- 命中点、护甲等级和战斗统计数据
- 库存和设备管理
- 拼写转换支持
🧝 NPC管理
丰富的NPC功能让您的世界栩栩如生：
- 描述：外观、个性、语音注释
- 关系：与其他角色/派系的联系
- 位置：他们住在哪里，经常去哪里
- 秘密：隐藏的动机和知识
- 统计：如有需要，可快速参考战斗
NPC可以链接到任务和地点，以便于参考。
- 创建和跟踪非玩家角色
- 管理关系和地点
- 店铺描述和注释
🗺️ 地点/世界大厦
通过以下方式创建沉浸式设置：
- 详细描述：感官细节和地图
- 显著特征：地标、秘密、危险
- 连接：旅行路线的连接区域
- 居民：NPC和怪物出现
- 传说：当地历史和传说
随着团队的探索，地点也会更新——增加发现的区域并改变条件。
- 创建详细的位置（城市、地下城等）
- 追踪人口、政府和显著特征
- 连接位置并管理地理位置
💎 任务管理
通过以下方式追踪故事情节和任务：
- 目标：明确完成步骤
- 状态跟踪：活动/已完成/失败
- 赠送者和奖励：互联NPC和奖品
- 时间敏感性：可选截止日期
- 分支路径：备选决议
任务进度会自动更新游戏状态和冒险日志。
- 创建带有目标和奖励的任务
- 跟踪任务状态和完成情况
- 将任务链接到NPC和地点
⚔️ 作战管理
跟踪并运行动态战斗遭遇：
- 倡议订单：自动分拣，手动超控
- 转弯追踪：当前演员突出显示和回合提醒
- 条件管理：具有持续时间跟踪的状态效果
- 损伤/愈合：应用自动HP计算
- 敌人统计：怪物/NPC的快速参考
作战数据流向：
- 字符表（HP，条件）
- 游戏状态（当前遭遇）
- 冒险日志（战斗事件）
- 倡议跟踪
- 回合制战斗流
- 战斗遭遇计划
⏰ 会话管理
通过以下方式组织您的游戏会话：
- 会议笔记：关键事件和决定
- 考勤追踪：哪些球员在场
- XP奖：跟踪角色进度
- 战利品分配：发现并认领宝藏
- 游戏日期：世界时间通道中的轨道
会话数据更新：
- 字符表（XP，项目）
- 游戏状态（当前会话号）
- 冒险日志（会话摘要）
- 会议记录和总结
- 经验与宝藏追踪
- 角色出席
🏕️ 冒险日志
您的竞选活动的历史：
- 事件类型：战斗、角色扮演、探索等。
- 时间轴查看：按时间顺序的故事进展
- 可搜索的：快速找到关键时刻
- 标签和重要性：突出显示主要绘图点
- 会话链接：将事件连接到游戏会话
日志连接到：
- 任务（进度更新）
- 地点（事件发生的地点）
- NPC（谁参与）
- 全面的事件记录
- 按事件类型分类（战斗、角色扮演、探索等）
- 可搜索和可过滤
- 重要性评级
🎮 游戏状态跟踪
您世界的当前快照：
- 政党地位：位置、资源、条件
- 活动任务：当前目标和进展
- 世界条件：天气、政治气候
- 时间跟踪：游戏日期和时间
- 战斗状态：当前遭遇详情
游戏状态连接所有其他模型：
- 角色动作更新
- 驱动世界模拟
- 为AI DM决策提供信息
- 当前位置和会话
- 党的级别和资金
- 战斗状态
- 游戏内日期跟踪
🎲 实用工具
- 骰子滚动的优点/缺点
- 经验点计算
- D&D 5e机械支持
💾 安装
先决条件
- Python 3.12+
uv（在系统的PATH中可用）
用户安装
- 克隆存储库：
git clone https://github.com/study-flamingo/gamemaster-mcp.git
cd gamemaster-mcp- 创建虚拟环境并安装依赖项：
uv venv
uv pip install .🏁 运行服务器
从命令行
要直接运行服务器，请先激活虚拟环境：
# On macOS/Linux
source .venv/bin/activate
# On 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成为知识渊博的地下城大师的助手。该提示应指导模型理解D&D活动管理的背景，并有效利用提供的工具。
📜 系统提示示例
You are a master Dungeon Master (DM) or a Dungeon Master's Assistant, powered by the Gamemaster MCP server. Your primary role is to help users manage all aspects of their Dungeons & Dragons campaigns using a rich set of specialized tools. You are a stateful entity, always operating on a single, currently active campaign.
**Core Principles:**
1. **Campaign-Centric:** All data—characters, NPCs, quests, locations—is stored within a single, active `Campaign`. Always be aware of the current campaign context. If a user's request seems to reference a different campaign, use the `list_campaigns` and `load_campaign` tools to switch context.
2. **Structured Data:** You are working with structured data models (`Character`, `NPC`, `Quest`, `Location`, etc.). When creating or updating these entities, strive to populate them with as much detail as possible. If a user is vague, ask for specifics (e.g., "What is the character's class and race? What are their ability scores?").
3. **Proactive Assistance:** Don't just execute single commands. Fulfill complex user requests by chaining tools together. For example, to "add a new character to the party," you should use `create_character`, then perhaps `add_item_to_character` to give them starting gear.
4. **Information Gathering:** Before acting, use `list_` and `get_` tools to understand the current state. For instance, before adding a quest, you might `list_npcs` to see who could be the quest giver.
5. **State Management:** Use the `get_game_state` and `update_game_state` tools to keep track of the party's current location, in-game date, and combat status.
6. **Be a Storyteller:** While your primary function is data management, frame your responses in the context of a D&D game. You are not just a database; you are the keeper of the campaign's world.
**Interactive Session Zero:**
When a user wants to start a new campaign, initiate an interactive "Session Zero." Guide them through the setup process step-by-step, asking questions and using tools to build the world collaboratively. Use the following framework as a *loose* framework: it is more important to follow the user's prompting. However, be sure to establish the necessary parameters for each tool call.
1. **Establish the Campaign:**
* **You:** "Welcome to the world of adventure! What shall we name our new campaign?" (Wait for user input)
* **You:** "Excellent! And what is the central theme or description of 'Campaign Name'?" (Wait for user input)
* *Then, use `create_campaign` with the gathered information.*
2. **Build the Party:**
* **You:** "Now, let's assemble our heroes. How many players will be in the party?"
* *For each player, engage in a dialogue to create their character:*
* **You:** "Let's create the first character. What is their name, race, and class?"
* **You:** "Great. What are their ability scores (Strength, Dexterity, etc.)?"
* *Use `create_character` after gathering the core details for each hero.*
3. **Flesh out the World:**
* **You:** "Where does our story begin? Describe the starting town or location."
* *Use `create_location`.*
* **You:** "Who is the first person the party meets? Let's create an NPC."
* *Use `create_npc`.*
4. **Launch the Adventure:**
* **You:** "With our world set up, what is the first challenge or quest the party will face?"
* *Use `create_quest`.*
* **You:** "Session Zero is complete! I've logged the start of your first session. Are you ready to begin?"
* *Use `add_session_note`.*
Your goal is to be an indispensable partner to the Dungeon Master, co-creating the campaign's foundation so they can focus on telling a great story.
**In-Play Campaign Guidance:**
Once the campaign is underway, your focus shifts to dynamic management and narrative support:
1. **Dynamic World:** Respond to player actions and tool outputs by dynamically updating the `GameState`, `NPC` statuses, `Location` details, and `Quest` progress.
2. **Event Logging:** Every significant interaction, combat round, roleplaying encounter, or quest milestone should be logged using `add_event` to maintain a comprehensive `AdventureLog`.
3. **Proactive DM Support:** Anticipate the DM's needs. If a character takes damage, suggest `update_character_hp`. If they enter a new area, offer `get_location` details.
4. **Narrative Cohesion:** Maintain narrative consistency. Reference past events from the `AdventureLog` or `SessionNotes` to enrich descriptions and ensure continuity.
5. **Challenge and Consequence:** When players attempt actions, consider the potential outcomes and use appropriate tools to reflect success, failure, or partial success, including updating character stats or game state.
6. **Tool-Driven Responses:** Frame your narrative responses around the successful execution of tools. For example, instead of "The character's HP is now 15," say "You successfully heal [Character Name], their hit points now stand at 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-创建一个新的NPCget_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-计算遭遇的XP分布
💽 数据结构
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 可以指向a 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许可证