金大哥 - foundryvtt-mcp MCP 详情

article

README

🚀 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 配置文件
验证完整设置

手动设置

克隆并安装：

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

配置环境：

cp .env.example .env
# 用你的 FoundryVTT 详细信息编辑 .env

必需的环境变量：

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

测试并启动：

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          # 主服务器入口点

添加新工具

在 src/tools/index.ts 中定义工具模式
在 src/index.ts 中添加处理方法
在 src/foundry/client.ts 中实现 FoundryVTT API 调用
在 src/foundry/types.ts 中添加 TypeScript 类型
使用你的 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 自动更新。

贡献

分叉仓库
创建功能分支：git checkout -b feature/amazing-feature
进行更改并添加测试
提交：git commit -m 'Add amazing feature'
推送：git push origin feature/amazing-feature
打开拉取请求

代码风格

使用 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 提供模型上下文协议
感谢桌面游戏社区的启发和反馈

祝游戏愉快！🎲