Warhammer MCP

基于AI的游戏大师助手，适用于Foundry VTT中的WFRP 4e

当前版本: 0.2.3 | 变更日志

通过模型上下文协议（MCP），将Claude Desktop连接到您的Foundry VTT游戏，实现智能战役管理、NPC生成以及旧世界内容创作。

---

🆕 v0.2.3 新增功能 (2025年10月11日)

增强功能

• 未知字段警告：角色更新工具现在提供无效字段名称的有用反馈

  • 显示哪些字段被忽略，并列出所有有效选项
  • 防止静默失败——用户立即知道是否输入了错误

• 增强特性报告：显示初始值与最终值及其修正项分解

  • 显示请求的初始值和计算的最终值
  • 显示来自天赋、物品和占星符号的修正项
  • 示例：I: 初始值=32, 最终值=34 (+2 来自天赋/物品)
  • 帮助理解WFRP4e的自动加成计算

• 改进的角色数据组织：新的conditions部分将状态效果与库存分开

  • 伤害、突变、疾病和心理状态现在位于专用部分
  • 物品部分现在仅显示物理库存（武器、盔甲、装备）
  • 更清晰、更直观的数据结构，符合WFRP4e的概念

• 命运/运气机制澄清：确认命运可以暂时超过运气（这不是一个错误！）

  • WFRP4e允许从奖励或燃烧运气后暂时超出
  • 每日刷新自然地强制上限

错误修复

• 修复空物品数组处理
• 增强描述截断（200字符）
• 添加传记提取（动机、野心）

测试

所有测试通过：角色检索（1.15）、混合验证（1.18）、不区分大小写的查找（1.19）、创建流程（1.21）、命运/运气管理（1.23）✅

查看CHANGELOG.md以获取完整详情。

---

🔄 上一版本：v0.2.2 (2025年10月6日)

关键错误修复

• 修复职业变更工具UUID错误：职业变更现在正确工作——工具从汇编包/ID数据中正确构建UUID
• 修复职业变更操作顺序：原子操作顺序防止角色在职业变更期间没有当前职业

新功能

• 韧性与决心系统：完整的NPC资源管理系统，镜像命运/运气（6个新工具）
  • 花费决心进行每日重投（类似于命运）
  • 燃烧韧性以避免死亡（类似于运气）
  • 因NPC的卓越行动奖励额外决心
  • 因史诗成就授予永久韧性
• 文件重命名：fortune-fate.ts重命名为fate-resilience.ts以提高清晰度（现在包含所有12个工具）

测试与质量

• 所有角色管理测试通过✅
• 所有职业晋升测试通过✅
• 所有腐败/突变测试通过✅
• 所有命运/运气测试通过✅
• 所有韧性/决心测试通过✅（新）
• 增强错误消息，带有详细的调试数据

查看CHANGELOG.md以获取完整详情。

---

🔄 上一版本：v0.2.1 (2025年10月5日)

关键错误修复

• 修复经验值计算错误：纠正了技能/特性晋升时经验值过高1000%的问题（例如，第11次技能晋升现在需要20经验值而不是220经验值）
• 实现缺失的汇编处理器：添加addItemFromCompendium基础设施以实现正确的WFRP4e集成

新功能

• 直接角色更新：新的foundry-update-character-info工具供GM调整，无需经验成本
• 直接技能/天赋更新：新的foundry-update-skill-talent工具用于角色设置和修正
• 汇编集成：新的add-skill-talent工具从汇编中添加技能/天赋及其官方效果
• 增强突变：add-mutation现在首先搜索汇编以查找具有适当机制的官方突变

查看CHANGES_2025-10-05.md以获取详细的技术信息。

---

关于此项目

该项目是Adam Dooley的原始Foundry VTT MCP Bridge的一个分支和增强版，专门针对Warhammer Fantasy Roleplay 4th Edition进行了改编和专业化。

致谢

原始项目：Foundry VTT MCP Bridge
原始作者：Adam Dooley (Patreon | YouTube)
分支维护者：Danny Castillo (IT Learning Consulting)
许可证：MIT 许可证（详见LICENSE）

特别感谢Adam Dooley创建了原始的MCP Bridge基础设施，使得这个专注于WFRP的分支成为可能。

这个分支有何不同

• WFRP 4e 专属：移除了D&D支持，现在完全专注于战锤奇幻角色扮演
• 65+ WFRP特定工具：职业晋升、腐败、突变、命运/运气、韧性/决心
• 自定义NPC生成器：创建平衡的NPC，具有基于经验值的晋升和种族特定特征
• 物种准确机制：正确计算伤口和固有天赋，适用于人类、矮人、精灵和半身人
• 随机表系统：创建和管理遭遇、战利品、事件和旧世界风味的随机表
• 增强的WFRP文档：全面指南、示例和特定于WFRP 4e机制的测试结果
• UI通知：当Claude进行更改时，在Foundry中实时显示通知

---

概览

Warhammer MCP将Claude Desktop连接到您在Foundry VTT中的WFRP 4e游戏，使Claude成为您的智能游戏大师助手。通过自然语言对话，Claude可以：

• 角色及NPC管理：访问特性、技能、天赋、腐败、命运/运气
• 内容生成：创建具有WFRP风味的自定义NPC、任务和战役内容
• 汇编搜索：使用自然语言查找生物、物品、法术和祈祷
• 骰子协调：请求玩家进行d100测试，带有交互式聊天按钮
• 战役追踪：多任务战役，带有进度仪表板
• 随机表：创建并滚动用于遭遇、事件、战利品等的表格
• WFRP机制：腐败、突变、致命伤、优势、疾病等

---

功能一览

🎭 核心功能（65+ 工具）

角色管理（5个工具） - 已更新！

• 获取角色详情（特性、技能、天赋、腐败、伤口）
• 列出所有玩家角色和NPC
• 新增：直接角色更新（统计、命运、运气）无需经验成本
• 新增：从汇编添加技能/天赋及其官方效果
• 新增：直接技能/天赋晋升更新供GM调整

职业与晋升（4个工具） - 已修复！

• 职业进展跟踪和经验值需求
• 提升特性、技能和天赋，修正的经验值计算
• 根据WFRP 4e规则计算经验值成本（现在使用适当的分层公式）
• 新增：具有适当UUID处理和原子操作的职业变更工具

战斗与条件（6个工具） - 增强！

• 按位置跟踪致命伤
• 优势系统管理
• 腐败和突变跟踪
• 已更新：从汇编添加具有官方效果的突变
• 疾病和感染管理

命运与运气（12个工具） - 扩展！

• 管理命运点数（每日重投）
• 跟踪运气点数（死亡保存）
• 燃烧运气以生存致命伤害
• 为卓越角色扮演奖励额外命运
• 为史诗成就授予运气（自动更新命运最大值）
• 新增：完整的韧性/决心系统用于NPC（6个工具）
  • get-resilience-resolve-status - 检查NPC韧性/决心
  • spend-resolve - NPC每日重投资源
  • spend-resilience - NPC死亡保存资源
  • refresh-resolve - 重置每日决心点数
  • add-resolve - 奖励额外决心
  • add-resilience - 授予永久韧性（罕见）

魔法与宗教（11个工具）

• 施法和引导
• 祈祷召唤和神恩
• 失控效果和腐败
• 学习和记忆新法术
• 跟踪罪孽点数并进行赎罪

库存与经济（5个工具）

• 管理角色库存
• 检查负重和惩罚
• 社会地位和收入计算
• 名誉影响

内容创作（8个工具）

• 自定义NPC生成器：根据种族、职业和经验值预算创建平衡的NPC
• 从汇编条目创建演员
• 创建具有WFRP主题的任务日记
• 战役仪表盘管理
• 具有旧世界美学的地图生成

随机表（5个工具） - 新增！

• 创建自定义RollTables，具有d100范围
• 列出并查看世界中的所有表格
• 在表格上滚动以获得随机遭遇、战利品、事件
• 删除表格

汇编与搜索（3个工具）

• 使用WFRP特定过滤器进行自然语言生物搜索
• 列出可用的汇编包
• 查询汇编中的丰富生物数据（统计数据、能力、特征）
• 增强生物索引以加快搜索速度
• 灵活搜索：名称、类型、特征、能力

骰子与测试（1个工具）

• 请求玩家进行特性或技能测试
• 聊天中的交互式d100掷骰按钮
• 自动成功/失败计算

场景与世界（2个工具）

• 获取当前场景信息
• 查询世界细节和系统版本

权限（3个工具）

• 管理玩家的角色所有权
• 分配和移除权限
• 列出友好NPC和队伍成员

---

支持的游戏系统

• WFRP 4e：完全原生支持，包括所有系统特定机制
• 可扩展性：架构支持添加其他系统（需要开发）

---

安装

先决条件

• Foundry VTT v13 或更高版本
• WFRP 4e 系统 已安装在Foundry VTT中
• Claude Desktop 具有MCP支持
• Claude Pro/Max计划（连接MCP所需）
• Windows（用于安装程序）或Node.js 18+（用于手动安装）

方案1：Windows安装程序（推荐）

视频指南（来自原始项目——基本过程相同）

1. 从发布页面下载最新的WarhammerMCP-Setup.exe
2. 运行安装程序——它将：
   • 安装捆绑Node.js的MCP服务器
   • 自动配置Claude Desktop
   • 可选安装Foundry模块
3. 重启Claude Desktop
4. 在Foundry VTT中，启用**“Warhammer MCP”**模块管理
5. 开始游戏！

方案2：手动安装

步骤1：安装Foundry模块

方法A：从清单URL

1. 在Foundry VTT中，转到附加模块
2. 点击“安装模块”
3. 粘贴此URL：https://raw.githubusercontent.com/IT-Learning-Consulting/warhammer-mcp/main/packages/foundry-module/module.json
4. 点击安装
5. 在您的世界中启用模块

方法B：手动构建

# 克隆此仓库
git clone https://github.com/IT-Learning-Consulting/warhammer-mcp.git
cd warhammer-mcp

# 安装依赖
npm install

# 构建所有包
npm run build

# 将模块复制到Foundry
cp -r packages/foundry-module/* /path/to/foundry/Data/modules/warhammer-mcp/

步骤2：安装MCP服务器

# 仍然在warhammer-mcp目录下
cd packages/mcp-server

# 服务器已在步骤1中构建
# 注意路径：/path/to/warhammer-mcp/packages/mcp-server/dist/index.js

步骤3：配置Claude Desktop

将以下内容添加到您的Claude Desktop配置文件中：

Windows：%APPDATA%\Claude\claude_desktop_config.json
macOS：/Library/Application Support/Claude/claude_desktop_config.json
Linux：/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "warhammer-mcp": {
      "command": "node",
      "args": [
        "C:\\path\\to\\warhammer-mcp\\packages\\mcp-server\\dist\\index.js"
      ],
      "env": {
        "FOUNDRY_HOST": "localhost",
        "FOUNDRY_PORT": "31415"
      }
    }
  }
}

重要：

• 替换C:\\path\\to\\warhammer-mcp为您实际的路径
• Windows上使用双反斜杠（\\）
• macOS/Linux上使用正斜杠（/）

步骤4：启动一切

1. 启动Foundry VTT并加载您的WFRP 4e世界
2. 启用**“Warhammer MCP”**模块
3. 启动Claude Desktop（MCP服务器会自动启动）
4. 查看Claude Desktop中的 🔌 锤子图标（表示已连接）

---

示例用法

一旦连接，您可以向Claude Desktop询问关于您的WFRP战役的信息：

角色信息

• "显示格鲁恩瓦尔德的特性及当前伤口"
• "凯瑟琳的腐败等级和突变是什么？"
• "列出派对的所有命运和运气点数"
• "检查汉斯的职业晋升进度"

NPC及内容创作

• "创建一个拥有100经验值的专长十字弓的矮人雇佣兵NPC"
• "生成一个拥有50经验值和一些腐败的人类骗子"
• "为村庄遭遇制作3个半身人镇民NPC"
• "创建一个关于调查阿尔道夫混沌邪教徒的任务"

战斗与机制

• "为战斗中的所有人掷躲避测试"
• "因为目睹恶魔而给格鲁恩瓦尔德增加2点腐败"
• "给汉斯的右臂造成致命伤"
• "跟踪当前战斗的优势"

魔法与宗教

• "艾拉拉知道哪些法术？"
• "让艾拉拉施放以太装甲"
• "威利牧师想要召唤西格玛的祈祷"
• "检查那个引导测试是否有失控"

随机表

• "创建一个具有10条目的雷克兰遭遇d100随机表"
• "制作一个包含各种旧世界硬币和物品的财宝表"
• "在德拉沃尔德事件表上掷骰"
• "列出我所有的随机表"

探索与战役

搜索与汇编

• "搜索汇编中所有混沌邪教徒NPC"
• "找到所有具有腐败特征的生物"
• "显示所有不死生物"
• "哪些物品能提升武器技能？"
• "当前场景中有何物？是否有敌人存在？"
• "为《内在之敌》创建战役仪表盘"
• "显示具有混沌特征的生物"

经济与地位

• "计算每月收入，角色的社会地位为银3"
• "为汉斯与贵族谈判进行社会地位测试"
• "卡特琳娜失去职位后，将其社会地位改为铜4"

---

工具参考

角色与职业工具

get-character - 获取完整角色表，包括所有WFRP统计数据
list-characters - 显示世界中的所有演员
get-career-advancement - 检查职业进度和经验值需求
advance-characteristic - 提高特性（WS、BS、S、T、I、Ag、Dex、Int、WP、Fel）
advance-skill - 通过经验值提高技能
advance-talent - 购买新天赋
change-career - 更改职业，具有适当的经验值成本（100/200基于完成情况）

战斗与条件

get-critical-wounds - 按位置列出所有致命伤
add-critical-wound - 应用致命伤
heal-critical-wound - 移除或治愈致命伤
get-advantage - 检查当前战斗的优势
modify-advantage - 增加或减少优势点数
**reset-adv