内容
# Foundry MCP 直播
将任何支持 MCP 的 AI 客户端（Claude Desktop、Claude Code、Codex CLI、Gemini CLI）直接连接到正在运行的 Foundry VTT 实例。实时访问角色、收藏、模块、控制台错误和完整的游戏 API — 无需复制粘贴数据，无需 API 令牌。
> 以 `foundry-mcp-live`（Foundry 模块 ID 和 GitHub 仓库名称相同）发布。v0.7.0 版本中更名为避免与 Foundry 包目录中的无关模块冲突；v0.7.1 版本更名仓库以匹配。
## 架构
```
Claude Desktop ─(stdio)─► proxy.mjs ──┐
│
Claude Code ─────(HTTP)─────────────►│
├──► MCP 服务器
Codex CLI ─────(HTTP)─────────────►│ (HTTP:3000)
│ │
Gemini CLI ─────(HTTP)─────────────►┘ │
▼
◄─(WS:3001)─►
Foundry 浏览器
```
- **MCP 服务器** (`server/server.js`, Node.js) — 在 `http://127.0.0.1:3000/mcp`（MCP HTTP 传输）和 `ws://127.0.0.1:3001`（Foundry 桥）本地运行。必须手动启动并保持运行。
- **Foundry 模块** (`module/`, 浏览器 JS) — 加载时连接到 WebSocket 服务器。处理针对实时 `game` 对象的工具请求。
- **stdio 代理** (`server/proxy.mjs`) — 适用于仅支持 stdio MCP 的客户端的桥（Claude Desktop、Claude Code）。
## 仓库布局
```
foundry-mcp-live/
├── module/ ← Foundry VTT 模块（复制/符号链接到 Foundry 的模块目录）
└── server/ ← Node.js MCP 服务器（使用 npm start 在本地运行）
```
## 设置
### 1. 克隆和安装
```bash
git clone https://github.com/DimitroffVodka/foundry-mcp-live.git
cd foundry-mcp-live/server
npm install
```
### 2. 安装 Foundry 模块
在 Foundry 中：**附加模块 → 安装模块** → 粘贴此清单 URL：
```
https://github.com/DimitroffVodka/foundry-mcp-live/releases/latest/download/module.json
```
Foundry 下载并安装它，就像其他模块一样。在世界的模块管理中激活它。
<details>
<summary>手动安装（如果无法使用清单 URL）</summary>
将此仓库的 `module/` 文件夹复制或符号链接到 Foundry 模块目录中，并重命名为 `foundry-mcp-live`：
- **Windows:** `%localappdata%\FoundryVTT\Data\modules\foundry-mcp-live`
- **Linux:** `/home/foundry/foundrydata/Data/modules/foundry-mcp-live`
- **macOS:** `~/Library/Application Support/FoundryVTT/Data/modules/foundry-mcp-live`
</details>
### 3. 启动 MCP 服务器
服务器基于 HTTP，必须在任何客户端连接之前运行：
```bash
cd server
npm start
# 或在 Windows 上：server\start.bat
# 或在 macOS/Linux 上：./start.sh
```
您应该看到：
```
[foundry-mcp] WebSocket 服务器监听 ws://localhost:3001
MCP HTTP 服务器监听 http://127.0.0.1:3000/mcp
```
保持此终端打开。服务器自动重新加载工具文件，但其他更改需要重启。
#### 可选：使用 systemd 在 Linux 登录/启动时运行
对于 Linux 工作站或小型专用主机，安装随附的用户服务：
```bash
./scripts/install-linux-user-service.sh
```
这会创建：
- `~/.config/systemd/user/foundry-mcp-live.service` — 一个用户级 systemd 服务，运行此签出中的 `server/server.js`。
- `~/.config/foundry-mcp-live/server.env` — 可选的环境变量覆盖，用于端口、写入/评估门、桥令牌和重启设置。
有用命令：
```bash
systemctl --user status foundry-mcp-live.service
journalctl --user -u foundry-mcp-live.service -f
systemctl --user restart foundry-mcp-live.service
systemctl --user disable --now foundry-mcp-live.service
```
用户服务通常在您登录时启动。要在机器启动前登录前启动此服务，请启用持久化：
```bash
sudo loginctl enable-linger "$USER"
```
systemd 服务保持与 `npm start` 相同的安全默认设置：写入、评估、自我测试和重启工具保持关闭，除非您取消注释或添加匹配的变量到 `~/.config/foundry-mcp-live/server.env`。
#### 可选：启用选择加入的工具
高级工具 **默认关闭**，在您启用它们之前不会出现在任何客户端的工具列表中。在启用之前阅读 [SECURITY.md](SECURITY.md)。
| 环境变量 | 添加 | 误用风险 |
|---|---|---|
| `FOUNDRY_MCP_ALLOW_WRITE=1` | 世界创作工具 | 创建、更新或删除持久的世界数据 |
| `FOUNDRY_MCP_ALLOW_EVAL=1` | `evaluate`、`job_result` | Foundry 浏览器上下文中的任意 JS；后台作业和有界大结果检索 |
| `FOUNDRY_MCP_ALLOW_SELF_TEST=1` | `self_test`（还需要写入） | 暂时创建和删除唯一标记的测试文档 |
| `FOUNDRY_RELAUNCH_ENABLED=1` | `relaunch_client` | 启动配置的本地 Chrome 并加入为配置的 GM |
**一次性**（仅限当前终端会话）：
```powershell
# Windows PowerShell
$env:FOUNDRY_MCP_ALLOW_WRITE = "1"
$env:FOUNDRY_MCP_ALLOW_EVAL = "1"
npm start
```
```bash
# macOS / Linux
FOUNDRY_MCP_ALLOW_WRITE=1 FOUNDRY_MCP_ALLOW_EVAL=1 npm start
```
**持久** — 编辑启动器，使每次启动都生效：
- Windows：编辑 [`server/start.bat`](server/start.bat) 并在 `node "%~dp0server.js"` 行上方添加 `set FOUNDRY_MCP_ALLOW_WRITE=1`（和/或 `set FOUNDRY_MCP_ALLOW_EVAL=1`）。
- macOS/Linux：在 shell 配置文件（`~/.zshrc`、`~/.bashrc`）中导出它们，或用自己的启动脚本包装 `npm start`。
启用后，服务器的启动输出是真实的来源。如果您设置了变量但新工具仍然未出现在 AI 客户端中，通常意味着环境变量实际上并未到达 node 进程 — 在启动前使用 `echo %FOUNDRY_MCP_ALLOW_WRITE%`（Windows）或 `echo $FOUNDRY_MCP_ALLOW_WRITE`（macOS/Linux）在同一 shell 中进行验证。
其他可调参数（端口、主机绑定、承载令牌）位于下面的完整 [环境变量](#环境变量) 表中。
### 4. 配置 AI 客户端
选择一个或多个。**所有四个可以同时连接到同一个正在运行的服务器**。
#### Claude Desktop
编辑 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）或 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
```json
{
"mcpServers": {
"foundry-vtt": {
"command": "node",
"args": ["C:\\path\\to\\foundry-mcp-live\\server\\proxy.mjs"]
}
}
}
```
使用 `proxy.mjs` 的绝对路径。重启 Claude Desktop。
#### Claude Code
Claude Code 原生支持 HTTP MCP，因此不需要代理：
```bash
claude mcp add --transport http foundry-vtt http://127.0.0.1:3000/mcp
```
使用 `claude mcp list` 确认 — 应该显示 `foundry-vtt: http://127.0.0.1:3000/mcp (HTTP) - ✓ 已连接`。
（如果您更喜欢，也可以通过 `proxy.mjs` 使用_stdio_回退：`claude mcp add foundry-vtt -- node /absolute/path/to/server/proxy.mjs`。）
#### Codex CLI
编辑 `~/.codex/config.toml`：
```toml
[mcp_servers.foundry]
url = "http://127.0.0.1:3000/mcp"
```
这是最低要求。要为特定工具需要显式批准，请添加每个工具的规则：
```toml
[mcp_servers.foundry.tools.evaluate]
approval_mode = "approve"
[mcp_servers.foundry.tools.get_actor]
approval_mode = "approve"
```
#### Gemini CLI
项目级（推荐） — 在项目根目录中创建 `.gemini/settings.json`：
```json
{
"mcpServers": {
"foundry-mcp-server": {
"url": "http://127.0.0.1:3000/mcp"
}
}
}
```
或从项目目录运行 `gemini mcp add foundry-mcp-server http://127.0.0.1:3000/mcp`。
### 5. 连接
1. 确保 MCP 服务器正在运行（步骤 3）。
2. 使用桥模块打开 Foundry VTT 世界。您应该看到通知：“MCP 桥已连接到 Claude Desktop”。
3. 启动 AI 客户端。Foundry 工具应该出现在其工具列表中。
## 更新服务器
**模块** 通过 Foundry 的正常更新流程更新。**服务器** 是一个单独的进程，手动更新 — 当它过期时，模块在 Foundry 中显示警告，并使用以下相同命令。
```bash
# Linux（systemd 服务）
cd ~/foundry-mcp-live && git pull
cd server && npm install
systemctl --user restart foundry-mcp-live
# Windows / macOS / 手动
git pull # 或重新下载最新版本
cd server && npm install # 依赖项更改时需要
# 然后重启服务器：start.bat（Windows）或 start.sh（Linux/macOS）
```
> 始终在拉取后运行 `npm install` — 一些修复是依赖项更改，仅靠 `git pull` 无法生效。
完整的多平台演练：**[docs/updating-the-server.md](docs/updating-the-server.md)**。
## 可用工具
| 工具 | 描述 |
|------|-------------|
| `get_game_info` | 系统、世界、版本、连接用户 |
| `list_actors` | 所有角色（按类型/文件夹可筛选） |
| `get_actor` | 按 ID 或名称获取完整角色数据 |
| `get_selected_token` | 当前选定的代币 + 角色 |
| `get_active_effects` | 特定角色的活动效果 |
| `list_modules` | 已安装的模块（默认激活） |
| `list_compendiums` | 所有收藏包及其元数据 |
| `search_compendium` | 收藏包内的文本搜索 |
| `get_compendium_document` | 收藏包中的完整文档 |
| `list_items` | 世界级物品 |
| `get_item` | 按 ID 或名称获取完整物品数据 |
| `get_scene` | 活动场景、网格、所有代币位置 |
| `get_data_model` | 系统数据模型模板 |
| `list_journals` | 日志条目 |
| `list_tables` | 掷骰表 |
| `list_macros` | 宏列表，带预览 |
| `get_macro` | 完整的宏源代码 |
| `get_console_errors` | 最近的控制台错误/警告 |
| `evaluate` | 在 Foundry 上下文中运行任意 JS |
| `job_result` | 轮询后台评估或以块为单位读取大结果 |
| `list_connected_bridges` | 显示哪些 Foundry 用户已连接（服务器本地工具） |
| `bridge_status` | 在无活动桥的情况下诊断桥和 Foundry 服务器可用性 |
| `relaunch_client` | 恢复死亡的配置 GM 浏览器会话（选择加入） |
| `self_test` | 保护的 Foundry 模式漂移烟雾测试（选择加入） |
有关完整工具模式和参数，请参见 [server/TOOLS.md](server/TOOLS.md)。
## 多用户路由
每个工具都接受一个可选的 `targetUser` 参数。默认是 GM。要以特定玩家身份运行工具，请传递该玩家的确切用户名：
```js
evaluate({ expression: "game.user.name", targetUser: "PlayerName" })
```
MCP 服务器通过连接时发送的标识帧跟踪每个连接的 Foundry 用户（`{ type: "hello", userId, userName, isGM }`）。使用 `list_connected_bridges` 查看谁可达。Foundry 的权限规则适用 — 针对 GM 仅限的 API 的玩家目标调用将产生与玩家在自己的控制台中看到的相同错误。
较旧的桥（v0.1.x），不发送 hello 帧，被视为旧 GM，因此未升级的安装仍然有效。
## 调试
从 Foundry 浏览器控制台，桥暴露了一个全局对象：
```js
mcpBridge.ws // WebSocket 实例
mcpBridge.handlers // 处理程序映射（可本地调用进行测试）
mcpBridge.errors // 错误缓冲区内容
mcpBridge.reconnect() // 强制重新连接
```
MCP 服务器记录到启动它的终端中的 stderr。
在没有客户端的情况下测试连接：
```bash
curl -i -X POST http://127.0.0.1:3000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
```
您应该获得一个 200 状态码和一个 `mcp-session-id` 头。
## 环境变量
| 变量 | 默认值 | 目的 |
|-----|---------|---------|
| `FOUNDRY_WS_PORT` | `3001` | Foundry 模块连接到的 WebSocket 端口 |
| `FOUNDRY_MCP_PORT` | `3000` | MCP 客户端连接到的 HTTP 端口 |
| `FOUNDRY_MCP_URL` | `http://127.0.0.1:3000/mcp` | `proxy.mjs` 用于查找 HTTP 服务器 |
| `FOUNDRY_MCP_ALLOW_EVAL` | `0` | 设置为 `1` 以启用 `evaluate` 工具（Foundry 上下文中的任意 JS）。参见 [SECURITY.md](SECURITY.md)。 |
| `FOUNDRY_URLS` | 空 | 用于重启安全 `bridge_status` 探测的 Foundry 来源的逗号分隔列表，例如 `http://localhost:30000`。 |
| `FOUNDRY_MCP_ALLOW_WRITE` | `0` | 设置为 `1` 以启用世界创作工具（`create_folder`、`create_actor`、`create_journal_entry` 等），这些工具会改变持久的世界数据。参见 [SECURITY.md](SECURITY.md)。 |
| `FOUNDRY_MCP_ALLOW_SELF_TEST` | `0` | 设置为 `1` 和 `FOUNDRY_MCP_ALLOW_WRITE=1` 一起，以注册受保护的 `self_test` 工具。 |
| `FOUNDRY_RELAUNCH_ENABLED` | `0` | 注册 `relaunch_client`。需要下面的 URL、GM 用户和 Chrome 路径变量。 |
| `FOUNDRY_RELAUNCH_URL` | 空 | 重新加入的显式 Foundry 来源，例如 `http://localhost:30000`。仅限环回，除非显式允许远程使用。 |
| `FOUNDRY_RELAUNCH_GM_USER` | 空 | 在加入页面上选择的精确 Foundry GM 用户名。 |
| `FOUNDRY_RELAUNCH_GM_PASSWORD` | 空 | 可选的 GM 密码。仅从服务器环境中读取；从不接受为工具参数或返回。 |
| `FOUNDRY_CHROME_PATH` | 空 | `puppeteer-core` 使用的 Chrome/Chromium 可执行文件的绝对路径。 |
| `FOUNDRY_CHROME_USER_DATA_DIR` | 空 | 可选的专用 Chrome 配置文件目录，用于重新启动的客户端。 |
| `FOUNDRY_RELAUNCH_ALLOW_REMOTE` | `0` | 设置为 `1` 以允许非环回 `FOUNDRY_RELAUNCH_URL`。 |
| `FOUNDRY_WS_HOST` | `127.0.0.1` | 桥 WebSocket 绑定的接口。默认是环回。仅当您已知要将桥暴露给 LAN 时才覆盖。 |
| `BRIDGE_TOKEN` | （未设置） | 共享密钥。如果设置，所有 MCP HTTP 请求必须发送 `Authorization: Bearer <token>`，Foundry 模块必须在 `localStorage.mcpBridgeToken` 中存储相同的值。参见 [SECURITY.md](SECURITY.md)。 |
## 备注
- WebSocket 连接每 5 秒自动重新连接一次，如果 Foundry 重新加载。每次都会重新发送 hello 帧。
- 控制台错误捕获在模块加载时开始 — `ready` 钩子之前的错误会丢失。
- `evaluate` 工具在 Foundry 客户端上下文中运行任意 JS — 默认禁用。启用 `FOUNDRY_MCP_ALLOW_EVAL=1`。对无边界工作使用 `background: true` 加 `job_result`；大于 256 KiB 的结果由句柄返回。
- 世界创作工具（创建角色/文件夹/日志）也会改变持久状态，默认禁用。启用 `FOUNDRY_MCP_ALLOW_WRITE=1`。参见 [SECURITY.md](SECURITY.md)。
- `relaunch_client` 是本地且选择加入的。保持其 Chrome 配置文件专用于 Foundry 自动化，并仅在服务器环境中存储任何 GM 密码。
- 两个端口仅绑定到 `127.0.0.1` — 不暴露给网络。
- AI 客户端不消耗 API 令牌。所有通信都是本地的：AI 客户端 ↔ MCP 服务器 ↔ Foundry 浏览器。
- 参见 [SECURITY.md](SECURITY.md) 获取威胁模型和选择加入身份验证。
## 发布新版本
1. 在 [module/module.json](module/module.json)、[server/package.json](server/package.json) 和 [server/server.js](server/server.js) 中增加 `version`；刷新 `server/package-lock.json` 中的根版本元数据。
2. 提交，然后标记并推送：`git tag v0.5.2 && git push --tags`。
3. [发布工作流](.github/workflows/release.yml) 构建 `module.zip` 并使用附加的 `module.json` + `module.zip` 发布 GitHub 版本，因此清单 URL `releases/latest/download/module.json` 然后自动指向新版本，因此 Foundry 的更新检查会选取它。
## 许可
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器