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 提供模型上下文協議
• 感謝桌面遊戲社區的啟發和反饋

---

祝遊戲愉快！🎲