内容
# 特里森的桥接工具
**通过与克劳德对话来运行你的Foundry VTT游戏。** 这是一个扩展的游戏大师工具集，用于Foundry VTT ↔ 克劳德桌面桥接工具 — 它让克劳德不仅可以_读取_你的世界，还可以_运行_它：构建遭遇战、驱动战斗追踪器、布置场景、管理NPC和战利品、编写日志、提示音乐等，所有这些都使用普通语言。
> **foundry-vtt-mcp**的分支版本，由 **亚当·杜利** （MIT）创建，它提供了整个基础桥接工具、安装程序和AI地图生成。此分支版本在此基础上添加了**40多种新的游戏大师工具**。与原作者无关 — 请参见[致谢](#致谢)。
- **Foundry VTT v13 / v14** · 适用于 **D&D 5e, SW5e, PF2e, DSA5, Cosmere RPG, WFRP4e** （大多数工具与系统无关；有些工具特定于系统）
- **克劳德桌面** 上的 **Pro 或 Max** 计划
- 📖 **完整的工具参考：** [`AI-TOOLSET.md`](AI-TOOLSET.md) — 将其放入克劳德工作区，以便它理解每个命令。
---
## 你可以做的事情
只需与克劳德对话；它会选择合适的工具。按主题游览：
### 🎭 叙事与交流
在角色中发布NPC对话、角色外笔记或表情符号到聊天室 · 私密地向特定玩家低语 · 进行隐藏的GM掷骰。
> _“让酒馆老板用角色身份迎接队伍，然后向盗贼低语秘密密码。”_
### ⚔️ 运行战斗
将敌人代币放到场景中 · 启动追踪器、掷骰决定先攻、推进回合 · 应用伤害/治疗 · 添加主动效果（增益、减益、状态） · 让NPC掷骰保存/技能/攻击 · 短休息和长休息。
> _“放置三个守卫在门口，开始战斗，并掷骰决定每个人的先攻。”_
### 🗺️ 构建和布置场景
创建或切换场景 · 生成AI战场地图（可选ComfyUI后端） · 添加墙壁、灯光、图块、法术/效果模板、地图注释和绘图。
> _“在左墙上添加闪烁的火炬光，在后面添加秘密门。”_
### 📚 管理内容和传说
撰写和**编辑**多页日志 · 与NPC链接的任务 · 掷骰表 · 文件夹用于整理 · 从世界内容构建可重复使用的**纲要包** （一个野兽志，一个战利品库）。
> _“写一个玩家可见的日志，描述废弃的寺庙，归档在位置下。”_
### 🧑🤝🧑 角色和战利品
查询属性、库存和能力 · 从提示或纲要创建NPC · 在角色之间转移物品 · 调整货币 · 奖励经验值 · 复制随从 · 管理代币所有权。
> _“将牧师的治疗药水交给战士，并奖励队伍300经验值。”_
### 🎵 氛围和掷骰
播放/停止播放列表并设置音量 · 请求玩家掷骰。
> _“播放酒馆音乐，并要求每个人进行感知检查。”_
### 🧹 内部管理（设计安全）
确认后删除演员、物品、日志（和单页）、场景、掷骰表、纲要包和场景对象，如游离的灯光/墙壁。
**安全模型：** 每个改变世界的工具都是**仅限GM**。桥接工具严格地在你的活跃世界**内部**工作 — 它**永远不会创建、覆盖或删除世界本身**，并且世界/系统配置是**只读**的。破坏性工具需要明确的`确认`。运行宏（任意代码）是**关闭**的，除非你在设置中启用。
👉 在 [`AI-TOOLSET.md`](AI-TOOLSET.md) 中查看完整的分类工具列表。
---
## 安装
桥接工具是**两个必须同时安装和保持同步的半部分**：
1. **Foundry模块** （在Foundry VTT内部运行），和
2. **MCP服务器** （一个小型Node进程，由克劳德桌面启动）。
从 [**最新版本**](https://github.com/triston-dev/tristons-bridge-fork/releases/latest) 下载 **`foundry-mcp-bridge.zip`** （模块） 和 **`foundry-mcp-server.zip`** （服务器）。
### 要求
- Foundry VTT **v13 或 v14**
- **克劳德桌面** 上的 **克劳德Pro 或 Max** 计划（MCP服务器需要付费计划）
- **Node.js 18+** （除非你使用Path B中的捆绑运行时基础安装程序）
- Windows 10/11 用于自动基础安装程序；其他操作系统通过源码（路径C）
- _(可选)_ 用于AI地图生成的具有≥ 8 GB VRAM的CUDA GPU
### 路径A — 你已经运行原始桥接工具（或早期分支版本）
只需覆盖两个zip文件：
1. **模块：** 将 `foundry-mcp-bridge/` 文件夹替换为 `foundry-mcp-bridge.zip` 中的内容，位于你的Foundry用户数据中的 `Data/modules/foundry-mcp-bridge/`。
2. **服务器：** 完全退出克劳德桌面，然后将 `foundry-mcp-server/` 文件夹替换为 `foundry-mcp-server.zip` 中的内容，位于你的 `FoundryMCPServer` 安装目录中（Windows： `%LOCALAPPDATA%\FoundryMCPServer\`）。 _(最小替代方案：仅替换 `foundry-mcp-server\packages\mcp-server\dist\backend.bundle.cjs`.)_
3. 重启克劳德桌面并重新加载你的世界。
### 路径B — 新安装，最简单（Windows：捆绑Node + 可选ComfyUI）
1. 使用原始项目的 [**Windows/Mac安装程序**](https://github.com/adambdooley/foundry-vtt-mcp/releases) 进行安装 — 它捆绑了Node运行时，配置了克劳德桌面，并可选地设置了ComfyUI地图生成。
2. 然后按照 **路径A** 中的方法应用此分支版本的两个zip文件。
### 路径C — 从源码（任意操作系统，自包含）
```bash
git clone https://github.com/triston-dev/tristons-bridge-fork.git
cd tristons-bridge-fork
npm install
npm run build:release
```
- **模块：** 将 `foundry-mcp-bridge.zip` 安装到 `Data/modules/` （或复制构建的 `packages/foundry-module` 到那里作为 `foundry-mcp-bridge/`）。
- **克劳德桌面：** 将服务器添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"foundry-mcp": {
"command": "node",
"args": ["ABSOLUTE/PATH/TO/tristons-bridge-fork/packages/mcp-server/dist/index.js"],
"env": { "FOUNDRY_HOST": "localhost", "FOUNDRY_PORT": "31415" }
}
}
}
```
配置文件位于 `%APPDATA%\Claude\claude_desktop_config.json`。 **Microsoft-Store** 克劳德安装使用 `%LOCALAPPDATA%\Packages\<…Claude…>\LocalCache\Roaming\Claude\claude_desktop_config.json`。
### 完成（所有路径）
1. 启动克劳德桌面，然后启动Foundry并以GM身份加载你的世界。
2. 在Foundry中： **模块管理 → 启用 “特里森的桥接工具”。**
3. 其设置应显示 **已连接**。询问克劳德 _“Foundry中的当前场景是什么？”_ 以确认。
> ⚠️ **不要重命名模块ID或其文件夹。** MCP服务器通过ID `foundry-mcp-bridge` 路由到模块；重命名它会破坏连接。
---
## 设置（Foundry → 模块设置 → 特里森的桥接工具）
- **启用MCP桥接工具** — 连接的总体开关（保持开启；显示已连接状态）。
- **连接类型** — _自动_ （推荐），_WebRTC_ （互联网/远程世界），或 _WebSocket_ （本地）。
- **允许写入操作** — 关闭 = 克劳德只能_读取_；开启 = 它可以修改世界内容。
- **允许宏执行** — **默认关闭**；启用 `execute-macro` 工具，运行任意代码。除非你信任连接的AI，否则保持关闭。
- **每请求的最大演员数量** — 大规模演员创建的安全上限。
- 重新连接/通知选项，以及 **增强生物索引** 和 **地图生成** 子菜单。
## 架构
```
克劳德桌面 ↔ MCP ↔ MCP服务器 ↔ WebSocket / WebRTC ↔ Foundry模块 ↔ Foundry VTT
↓
ComfyUI（可选AI地图生成）
```
- **Foundry模块** — Foundry VTT内部的安全、仅限GM的数据访问。
- **MCP服务器** — 克劳德桌面启动的Node进程；与模块通信。
- **无API密钥** — 使用您现有的克劳德桌面订阅。
- **远程游戏** — WebRTC允许服务器访问在其他地方托管的Foundry世界。
## 构建和贡献
```bash
npm install
npm run build:release # 构建共享 + 服务器捆绑包 + Foundry模块
npm run typecheck
```
此仓库的远程仓库： `origin` → 此分支， `upstream` → [adambdooley/foundry-vtt-mcp](https://github.com/adambdooley/foundry-vtt-mcp) （以便您可以拉取上游更新）。欢迎提出问题和PR。
## 致谢
- **原始项目：** [foundry-vtt-mcp](https://github.com/adambdooley/foundry-vtt-mcp) 由 **亚当·杜利** 创建 — 基础桥接工具、Windows/Mac安装程序和ComfyUI地图生成。 © 2025 亚当·杜利，MIT。
- **此分支：** 扩展的游戏大师工具集，由 [**triston-dev**](https://github.com/triston-dev) 创建。有关具体添加内容，请参见 [`NOTICE.md`](NOTICE.md)。
- 与原作者无关。
## 许可证
MIT — 参见 [`LICENSE`](LICENSE)（原始版权在内）。可选安装程序/地图生成使用的捆绑组件（例如D&D战场地图SDXL模型、7-Zip）具有其自己的许可条款；请参见安装程序通知。
