FoundryVTT MCP Server

使用说明（Markdown格式）

• 项目简介

  • 该仓库实现了一个基于 MCP 的服务器，用于提供对 FoundryVTT 世界数据的标准化访问、外部工具调用能力以及可定制的提示模板渲染，旨在为大语言模型（LLM）提供稳定的上下文服务和对外部功能的扩展入口。

• 主要功能点

  • MCP 服务端核心：支持通过 JSON-RPC 与客户端进行资源读取、工具调用、以及提示模板获取等请求与响应。
  • 资源管理：暴露 FoundryVTT 中的 Actors、Items、Scenes、Journals、Users、World 设置等资源，通过标准化接口提供数据访问。
  • 工具注册与执行：注册并执行一组工具（如 Dice Roll、搜索 Actors/Items、获取世界信息、诊断等），支持参数校验与错误处理。
  • 会话与诊断：包含连接管理、诊断系统、健康检查等模块，帮助监控服务器状态与 FoundryVTT 的可用性。
  • 多传输支持：服务器设计可扩展，现实现基于 MCP Server 与 Stdio 传输，未来可扩展到 SSE、WebSocket 等传输方式。
  • 集成能力：与 FoundryVTT 的 REST API 模块（可选）以及 Socket.IO 实现互补，支持多种身份验证方式。

• 安装步骤

  1. 安装依赖并构建
     • 克隆仓库并进入项目目录
     • npm install
     • npm run setup-wizard（可选，自动探测 FoundryVTT 配置并生成 .env）
     • npm run build
     • npm start
  2. 运行前提
     • Node.js 18 及以上
     • FoundryVTT 服务已运行且 world 已加载
     • 如使用 REST API 模块，请根据需要配置 FOUNDRY_API_KEY
  3. 运行后端服务器
     • 服务器启动后，它将监听 MCP 客户端的请求（资源读取、工具调用等），并通过 MCP 协议与客户端进行交互。

• 服务器配置（MCP 客户端的连接信息，JSON，示例仅供参考） 注：MCP 客户端需要提供服务器启动信息以建立连接。以下信息对应本仓库的默认实现与启动方式： { "serverName": "foundry-mcp-server", "command": "node", "args": ["dist/index.js"] } 说明:

  • serverName: MCP 服务器在客户端中的标识名称，默认值为 foundry-mcp-server。
  • command: 启动服务器的命令（在生产环境通常为 node）。
  • args: 启动命令的参数，这里指向编译输出的入口文件（dist/index.js）。 脚本启动通常遵循“构建后启动”的流程，即先 npm run build 再 npm start，生成的 dist 目录中的入口文件将被执行以启动 MCP 服务器。

• 基本使用方法

  • 启动后，LLM 客户端可通过 MCP 的 JSON-RPC 请求访问：
    • 读取资源：如 foundry://actors、foundry://items 等，获取世界数据。
    • 调用工具：如 roll_dice、search_actors、get_world_summary 等，执行外部功能并返回结果。
    • 获取 Prompt/模板：通过 MCP 资源与工具能力，定制化对话行为。
  • 日常开发与调试时，可以结合日志输出与健康诊断，快速定位连接、权限、或数据问题。

• 备注

  • 若需进一步自定义工具、资源、或提示模板，请参考 src 目录下的相关实现模块（tools、resources、diagnostics、foundry 等）。
  • 本仓库兼具完整的服务端实现与多模块协作能力，适合作为将来对接大语言模型的上下文服务端。