Foundryvtt MCP

🚀 FoundryVTT MCP 服务器

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

🚀 快速开始

本服务器可让你借助 AI 助手，通过自然语言与桌面游戏会话交互，实现查询角色、掷骰子、生成内容和管理游戏世界等操作。

✨ 主要特性

核心功能

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

实时集成

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

人工智能赋能特性

• 🧠 战术建议 - 获取战斗建议和策略提示
• 🎪 故事辅助 - 生成情节钩子和叙事元素
• 🎨 世界构建 - 按需创建地点、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
# 用你的 FoundryVTT 详细信息编辑 .env

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

💻 使用示例

基础用法

向你的 AI 助手提出如下问题：

掷骰子：

• "掷 1d20 + 5 进行攻击掷骰"
• "掷 4d6 弃最低值以确定能力值"
• "掷 2d10 + 3 计算伤害"

游戏数据：

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

内容生成：

• "生成一个随机的 NPC 商人"
• "为挑战等级 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 系统健康状态"
• 错误分析： "诊断近期错误并提供建议"
• 日志搜索： "搜索过去一小时内包含 'connection' 模式的日志"
• 近期问题： "显示近期错误日志"

高级诊断

使用 本地 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	❌	请求超时时间（毫秒）	10000
FOUNDRY_RETRY_ATTEMPTS	❌	重试失败的请求	3
CACHE_TTL_SECONDS	❌	缓存持续时间	300

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

工具模式

roll_dice

{
  "formula": "1d20+5",
  "reason": "Attack roll against goblin"
}

search_actors

{
  "query": "goblin",
  "type": "npc",
  "limit": 10
}

generate_npc

{
  "race": "human",
  "level": 5,
  "role": "merchant",
  "alignment": "neutral good"
}

集成示例

Claude Desktop 配置

添加到你的 Claude Desktop MCP 设置中：

{
  "mcpServers": {
    "foundry": {
      "command": "node",
      "args": ["/path/to/foundry-mcp-server/dist/index.js"],
      "env": {
        "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({
  command: "node",
  args: ["./dist/index.js"],
});

const client = new Client(
  {
    name: "foundry-client",
    version: "1.0.0",
  },
  {
    capabilities: {},
  },
);

await client.connect(transport);

// 掷骰子
const result = await client.request({
  method: "tools/call",
  params: {
    name: "roll_dice",
    arguments: {
      formula: "1d20+5",
      reason: "Initiative roll",
    },
  },
});

路线图

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 'Add amazing feature'
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 工具进行全面诊断，或在启动时检查服务器日志以获取详细状态信息。

📚 常见问题

• 连接被拒绝：确保 FoundryVTT 在配置的端口上运行
• 身份验证失败：验证 .env 中的 API 密钥或用户名/密码
• 搜索结果为空：安装并启用 "Foundry Local REST API" 模块
• 功能受限：完整功能需要使用 REST API 模块

📖 详细故障排除指南：TROUBLESHOOTING.md

支持

• 问题反馈：通过 GitHub Issues 反馈 bug 和提出功能请求
• Discord 交流：FoundryVTT Discord #api-development
• 文档查阅：FoundryVTT API 文档
• 故障排除：TROUBLESHOOTING.md

致谢

• 感谢 FoundryVTT 团队提供优秀的虚拟桌面平台
• 感谢 Anthropic 提供模型上下文协议
• 感谢桌面游戏社区的启发和反馈

---

祝游戏愉快！🎲