FoundryVTT MCP服务器

一个与FoundryVTT集成的模型上下文协议（MCP）服务器，允许AI助手与您的桌面游戏会话进行交互。通过自然语言查询角色、掷骰子、生成内容并管理您的游戏世界。

功能

核心功能

• 🎲 掷骰子 - 使用标准RPG符号掷骰子
• 🔍 数据查询 - 搜索角色、物品、场景和日志条目
• 📊 游戏状态 - 访问当前场景、战斗状态和世界信息
• 🎭 内容生成 - 生成NPC、战利品和随机遭遇
• 📝 规则查询 - 查询游戏规则和机制信息

实时集成

• 🔄 实时更新 - 使用WebSocket连接实现实时游戏状态
• ⚔️ 战斗管理 - 跟踪先攻顺序和战斗状态
• 👥 用户感知 - 查看谁在线及其状态

AI增强功能

• 🧠 战术建议 - 获取战斗建议和策略提示
• 🎪 故事辅助 - 生成情节钩子和叙述元素
• 🎨 世界构建 - 按需创建地点、NPC和任务

安装

先决条件

• Node.js 18+
• 运行并可访问的FoundryVTT服务器
• 兼容MCP的AI客户端（如Claude Desktop等）

快速设置（推荐）

🧙‍♂️ 互动安装向导：

git clone <repository-url>
cd foundry-mcp-server
npm install
npm run setup-wizard

安装向导将：

• 自动检测您的FoundryVTT服务器
• 测试连接性和认证
• 生成您的.env配置文件
• 验证完整的安装设置

手动设置

1. 克隆并安装：

git clone <repository-url>
cd foundry-mcp-server
npm install

2. 配置环境：

cp .env.example .env
# 编辑.env以包含您的FoundryVTT详细信息

3. 必需的环境变量：

FOUNDRY_URL=http://localhost:30000
FOUNDRY_API_KEY=your_api_key_here
# 或使用用户名/密码：
FOUNDRY_USERNAME=your_username
FOUNDRY_PASSWORD=your_password

4. 测试并启动：

npm run test-connection  # 验证设置
npm run build
npm start

开发模式

npm run dev

FoundryVTT配置

MCP服务器支持两种安全的本地认证方法：

选项1：本地REST API模块（🔒 推荐）

优点：

• ✅ 100%本地 - 没有外部依赖或第三方服务
• ✅ 最大隐私 - 您的游戏数据永远不会离开您的网络
• ✅ 完全控制 - 您拥有并管理所有认证
• ✅ 更好性能 - 直接本地API访问
• ✅ 完整API访问 - 对所有FoundryVTT功能的完全访问

设置：

1. 安装Foundry本地REST API模块：
   • 在FoundryVTT中：设置 → 附加模块 → 安装模块
   • 粘贴：https://github.com/laurigates/foundryvtt-mcp/releases/latest/download/module.json
2. 在您的世界中启用该模块
3. 前往设置 → 配置设置 → 模块设置
4. 找到**“Foundry本地REST API”并勾选“启用REST API”**
5. 复制生成的API密钥
6. 添加到您的.env文件中：

   FOUNDRY_URL=http://localhost:30000
   FOUNDRY_API_KEY=your_local_api_key_here
   

选项2：用户名/密码（备用）

使用情况： 当本地REST API模块不可用或用于简单设置时。

限制： 一些高级功能可能无法正常工作。

1. 确保您的FoundryVTT用户具有适当的权限
2. 将凭据添加到.env文件中：

   FOUNDRY_URL=http://localhost:30000
   FOUNDRY_USERNAME=your_username
   FOUNDRY_PASSWORD=your_password
   

比较表

特性	本地REST API模块	用户名/密码
隐私	✅ 100%本地	✅ 100%本地
安全性	✅ API密钥认证	⚠️ 密码认证
性能	✅ 直接API访问	⚠️ 只能WebSocket
功能	✅ 完整API访问	❌ 功能有限
设置	⚠️ 需要模块安装	✅ 简单凭据
可靠性	✅ 稳定API	⚠️ 连接依赖

必需的权限（所有方法）

您的FoundryVTT用户需要以下权限：

• 查看角色、物品、场景和日志
• 创建和修改日志条目（用于内容生成）
• 访问汇编数据
• 使用掷骰子API

使用

基本查询

询问您的AI助手如下内容：

掷骰子：

• “掷1d20+5作为攻击掷骰”
• “掷4d6丢弃最低值作为属性得分”
• “掷2d10+3作为伤害”

游戏数据：

• “显示此场景中的所有NPC”
• “查找队伍库存中的魔法武器”
• “当前战斗的先攻顺序是什么？”
• “搜索治疗药水”

内容生成：

• “生成一个随机的商人NPC”
• “为CR 5遭遇生成战利品”
• “生成一个带有NPC和情节钩子的酒馆”

高级功能

规则查询：

• “查阅抓抱规则”
• “火球术如何运作？”
• “被吓到的条件是什么？”

战术建议：

• “为对抗龙提供建议战术”
• “我们的法师这回合应该做什么？”
• “分析这个战斗遭遇”

世界构建：

• “创建一个神秘森林地点”
• “生成一个涉及失踪商人的支线任务”
• “设计一个适合8级角色的魔法物品”

可用工具

数据访问

• search_actors - 查找角色、NPC、怪物
• search_items - 查找装备、法术、消耗品
• search_journals - 搜索笔记和手册
• get_scene_info - 当前场景详情
• get_actor_details - 角色详细信息

游戏机制

• roll_dice - 使用任何公式掷骰子
• update_actor_hp - 修改角色生命值
• get_combat_status - 战斗状态和先攻顺序
• lookup_rule - 游戏规则和法术描述

内容生成

• generate_npc - 创建随机NPC
• generate_loot - 创建适合等级的战利品
• roll_table - 随机遭遇、事件、天气
• suggest_tactics - 战斗建议和策略

诊断及系统健康

• get_system_health - 服务器性能和健康指标
• get_recent_logs - 获取过滤后的FoundryVTT日志
• search_logs - 使用正则表达式搜索日志
• diagnose_errors - 分析错误并提供故障排除建议

可用资源

服务器公开了这些FoundryVTT资源：

• foundry://world/info - 世界和战役信息
• foundry://world/actors - 世界中的所有角色
• foundry://scene/current - 当前活动场景
• foundry://combat/current - 活跃战斗状态
• foundry://compendium/spells - 法术数据库
• foundry://compendium/monsters - 怪物数据库

配置

服务器设置

编辑.env来自定义：

# 日志
LOG_LEVEL=info  # debug, info, warn, error

# 性能
FOUNDRY_TIMEOUT=10000      # 请求超时（毫秒）
FOUNDRY_RETRY_ATTEMPTS=3   # 重试失败请求
CACHE_TTL_SECONDS=300      # 缓存数据5分钟

安全

• 尽可能使用API密钥而不是密码
• 将FoundryVTT用户的权限限制到最小必要范围
• 仅在内部网络上运行服务器
• 监控日志以查找可疑活动

诊断及故障排除

内置诊断

服务器包括全面的诊断工具，帮助解决连接和性能问题：

连接测试：

# 测试完整的MCP连接和功能
npm run test-connection

# 清洁构建和测试设置
npm run setup

诊断工具（通过AI助手）：

• 系统健康：“获取FoundryVTT系统健康状态”
• 错误分析：“诊断最近的错误并提供建议”
• 日志搜索：“搜索过去一小时内‘连接’模式的日志”
• 近期问题：“显示最近的错误日志”

高级诊断

当使用本地REST API模块时，您将获得访问高级诊断功能：

• 🔍 实时日志分析 - 监控FoundryVTT控制台输出和通知
• 📊 系统健康指标 - 服务器性能、内存使用和客户端连接
• 🎯 错误模式识别 - 自动检测常见问题
• 💡 智能建议 - 上下文感知的故障排除建议
• 📈 性能监控 - 跟踪服务器正常运行时间和响应时间

连接问题

# 测试FoundryVTT连接
curl http://localhost:30000/api/status

# 检查服务器日志
npm run dev  # 显示详细的日志

常见问题

“无法连接到FoundryVTT”

• 验证FOUNDRY_URL是否正确
• 检查FoundryVTT是否正在运行
• 确保已启用API访问

“身份验证失败”

• 验证API密钥或用户名/密码
• 检查FoundryVTT中的用户权限
• 确保用户未被禁用/限制

“找不到工具”错误

• 更新到最新服务器版本
• 检查工具名称拼写
• 查看日志中的可用工具

开发

项目结构

src/
├── config/           # 配置管理
├── foundry/          # FoundryVTT客户端和类型
├── tools/            # MCP工具定义
├── resources/        # MCP资源定义
├── utils/            # 工具和日志
└── index.ts          # 主服务器入口点

添加新工具

1. 在src/tools/index.ts中定义工具模式
2. 在src/index.ts中添加处理方法
3. 在src/foundry/client.ts中实现FoundryVTT API调用
4. 在src/foundry/types.ts中添加TypeScript类型
5. 使用您的AI助手进行测试

测试

# 运行测试
npm test

# 运行覆盖率测试
npm run test:coverage

# 代码检查
npm run lint

构建

# 开发构建
npm run build

# 清洁构建
npm run clean && npm run build

API参考

环境变量

变量	必需	描述	默认值
FOUNDRY_URL	✅	FoundryVTT服务器URL	-
FOUNDRY_API_KEY	⭐	认证API密钥	-
FOUNDRY_USERNAME	⭐	用户名（无API密钥时）	-
FOUNDRY_PASSWORD	⭐	密码（无API密钥时）	-
LOG_LEVEL	❌	日志详细程度	info
NODE_ENV	❌	环境模式	development
FOUNDRY_TIMEOUT	❌	请求超时（毫秒）	1[10000
FOUNDRY_RETRY_ATTEMPTS	❌	重试失败请求次数	3
CACHE_TTL_SECONDS	❌	缓存持续时间	300

⭐ 需要API密钥或用户名/密码之一

工具模式

roll_dice

{
  "formula": "1d20+5",
  "reason": "对哥布林的攻击掷骰"
}

search_actors

{
  "query": "哥布林",
  "type": "npc",
  "limit": 10
}

generate_npc

{
  "种族": "人类",
  "等级": 5,
  "角色": "商人",
  "阵营": "中立善良"
}

集成示例

Claude Desktop配置

添加到您的Claude Desktop MCP设置：

{
  "mcpServers": {
    "foundry": {
      "命令": "node",
      "参数": ["/path/to/foundry-mcp-server/dist/index.js"],
      "环境": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_API_KEY": "your_api_key_here"
      }
    }
  }
}

自定义MCP客户端

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  命令: "node",
  参数: ["./dist/index.js"],
});

const client = new Client(
  {
    名称: "foundry-client",
    版本: "1.0.0",
  },
  {
    能力: {},
  },
);

await client.connect(transport);

// 掷骰子
const 结果 = await client.request({
  方法: "tools/call",
  参数: {
    名称: "roll_dice",
    参数: {
      公式: "1d20+5",
      原因: "先攻掷骰",
    },
  },
});

发展路线图

版本0.2.0

• 战斗管理工具（开始/结束战斗，推进先攻顺序）
• 令牌操作（移动，更新状态效果）
• 场景导航和切换
• 播放列表控制和环境音效

版本0.3.0

• 角色表编辑（升级等级，添加装备）
• 日记条目创建和编辑
• 宏执行和管理
• 高级内容生成（地牢，带有完整统计数据的NPC）

版本1.0.0

• 多世界支持
• 用户权限管理
• 外部触发器的Webhook支持
• 性能优化和缓存
• 完全覆盖测试
• Docker部署

文档

完整的API文档位于docs/目录中，从TypeScript源代码和JSDoc注释自动生成。

📖 查看文档

本地开发：

npm run docs        # 生成文档
npm run docs:serve  # 生成并本地提供

在线： 浏览此仓库中的docs/文件夹或访问GitHub Pages站点（如果已启用）。

📚 文档内容

• FoundryClient API - 包含示例的完整客户端文档
• TypeScript接口 - 所有数据结构和类型定义
• 配置 - 环境变量和设置选项
• 实用工具 - 辅助函数和日志
• 使用示例 - 常见操作的代码示例

文档会在源代码更改时通过GitHub Actions自动更新。

贡献

1. 分叉仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 进行更改并添加测试
4. 提交：git commit -m '添加惊人的功能'
5. 推送：git push origin feature/amazing-feature
6. 打开拉取请求

代码风格

• 使用TypeScript严格模式
• 遵循现有的命名约定
• 为公共API添加JSDoc注释
• 为新功能编写测试
• 使用有意义的提交消息

许可证

MIT许可证 - 详情见LICENSE文件。

故障排除

🔍 快速诊断

npm run test-connection      # 测试FoundryVTT连接性
npm run setup-wizard        # 重新运行互动安装向导

🏥 健康检查

使用get_health_status MCP工具进行全面诊断，或在启动期间检查服务器日志以获取详细状态信息。

📚 常见问题

• 连接拒绝：确保