内容
# Obsidian D&D MCP
> 状态：实验性。目前的重点是清晰的库结构、有效的 MCP 访问层和可重复使用的示例。
## 概述
Obsidian D&D MCP 是用于 AI 辅助桌面 RPG 战役中持久战役记忆的框架。
它使用 Obsidian 库作为长期记忆层，使用 MCP 服务器作为结构化访问层。目标是帮助 AI 助手查询、更新和保存战役上下文，以跨长时间运行的会话。
该仓库包括一个公共的 `example-vault` 示例库，展示了预期的结构，但它不是一个完整的战役。
## 适用人群
该项目适用于：
- AI 辅助桌面 RPG 战役
- 使用 Obsidian 的地下城主
- 需要持久战役记忆的玩家
- 需要连续性的长时间战役
尤其是在聊天记录不足以维持战役一致性时，它非常有用。
## 快速开始
总体来说：
1. 克隆仓库。
2. 安装 MCP 服务器依赖项。
3. 复制或适配示例库。
4. 配置服务器指向本地 Obsidian 库。
5. 启动 MCP 服务器。
6. 将其连接到首选的 MCP 兼容 AI 客户端。
7. 验证库工具可用。
8. 在开始或恢复战役之前，要求助手检查库索引。
克隆仓库并安装服务器依赖项：
```bash
git clone https://github.com/Svarion317/obsidian-dnd-mcp.git
cd obsidian-dnd-mcp/server
npm install
```
从示例结构创建工作库：
```bash
cp -R ../examples/example-vault ../my-campaign-vault
```
配置服务器环境：
```bash
cp .env.example .env
```
然后编辑 `.env` 并将库路径设置为本地库文件夹。
启动 MCP 服务器：
```bash
npm start
```
确切的客户端连接过程取决于正在使用的 AI 客户端。请参考客户端的 MCP 文档和 `server/README.md` 以获取设置详细信息。
## 问题
长时间运行的 AI 辅助战役可能会随着时间推移而失去连续性。
常见的失败点包括：
- 遗忘的角色细节
- 过时的库存
- 不一致的 NPC 行为
- 脱节的世界构建
- 未解决的剧情线索
- 战役历史埋在聊天记录中
- 战斗状态仅凭记忆处理
聊天记录本身并不是一个可靠的战役数据库。
## 解决方案
该项目将战役记忆与聊天记录分离。
它结合了：
- Obsidian 用于持久笔记
- MCP 用于结构化库访问
- 模块化战役文件
- DM 操作说明
- 战役状态更新
- 战斗准备笔记
AI 可以在响应之前检查相关文件，而不是仅依赖当前对话。
## 高级工作流程
```text
Obsidian 库
|
v
MCP 服务器
|
v
AI 助手
|
v
读取相关上下文
|
v
运行或支持战役
|
v
准备库更新
|
v
Obsidian 库
```
## 记忆管道
库组织为一个记忆管道。每一层都有特定的角色，以便 AI 可以仅加载当前场景所需的上下文。
### 角色层
角色文件是玩家角色的真实来源。
它们可以包括：
- 角色卡
- 库存
- 背景
- 目标
- 个人历史
### 战役状态层
战役状态跟踪战役中当前真实的内容。
它可以包括：
- 当前位置
- 活动目标
- 最近的事件
- 开放的问题
- 重要的后果
- 会话记录
历史笔记应与活动状态分开，以便当前信息不会被埋没。
### 世界构建层
世界构建文件存储可重复使用的设置信息。
它们可以包括：
- 位置
- 派系
- 组织
- 宇宙论
- 谜团
- 秘密
- 历史事件
### NPC 层
NPC 文件使重复出现的角色保持一致。
它们可以包括：
- 身份
- 角色
- 动机
- 关系
- 已知信息
- 秘密
- 当前状态
### DM 指令层
DM 指令文件定义了 AI 如何运行和维护战役。
它们可以包括：
- 叙事指南
- 连续性规则
- 咨询规则
- 更新程序
- 战役管理程序
### 战斗层
战斗有自己的工作流程，因为战斗状态在聊天中容易丢失。
示例库包括以下文件：
- 遭遇设计
- 战斗平衡
- 活动遭遇跟踪
## 仓库结构
```text
examples/
└── example-vault/
├── 00_Campagna/
├── 01_Personaggio/
├── 02_Istruzioni_DM/
├── 03_Combattimento/
├── 04_Manuali/
└── 05_Template/
server/
README.md
```
- `examples/example-vault/`：公共演示库，展示推荐的结构。
- `examples/example-vault/00_Campagna/`：战役状态、存档、NPC 和世界构建。
- `examples/example-vault/01_Personaggio/`：示例角色卡、库存和背景文件。
- `examples/example-vault/02_Istruzioni_DM/`：AI 地下城主的操作说明。
- `examples/example-vault/03_Combattimento/`：战斗准备和活动遭遇文件。
- `examples/example-vault/04_Manuali/`：手册的占位符。不包括任何 D&D 手册。
- `examples/example-vault/05_Template/`：战役笔记的可重复使用模板。
- `server/`：MCP 服务器，公开结构化的库工具。
- `README.md`：项目概述。
## 示例库
公共示例库位于：
```text
examples/example-vault/
```
它是一个演示库。它展示了如何组织战役记忆、模板、DM 指令和战斗笔记。
它不包括：
- 私人战役库
- 完整的、可玩的战役
- 官方的 D&D 规则书
- 受版权保护的 manual 内容
`04_Manuali` 目录仅作为占位符。请仅在您自己的私人库中添加您允许使用的材料。
## 典型工作流程
### 准备战役
在开始之前，准备 AI 需要的最低限度记忆以保持一致：
- 角色卡
- 角色库存
- 角色背景
- 起始战役状态
- 核心世界构建笔记
- DM 关于基调和操作规则的说明
在第一次会话之前与 AI 讨论战役世界，然后在库中记录同意的信息。
有用的主题包括：
- 基调和类型
- 起始位置
- 主要派系
- 重要冲突
- 已知的谜团
- 角色不知道的秘密
- 角色已经知道的内容
### 开始战役
1. 复制或适配示例库结构。
2. 填写准备好的角色、战役状态和世界构建文件。
3. 将 MCP 服务器连接到库。
4. 在游戏开始之前，要求 AI 查询相关文件。
### 恢复会话
在会话开始时，AI 应检查当前状态和任何相关的角色、NPC、世界构建或战斗文件。
目标是从记录的战役记忆中恢复，而不是从模糊的聊天回忆中。
### 更新战役
在重要事件发生后，更新库。
典型的更新包括：
- 当前状态更改
- 新的 NPC 信息
- 库存更改
- 已完成的任务
- 新的未解决的线索
- 玩家行为的后果
- 会话记录或战役存档
## 战斗工作流程
战斗笔记应在可能的情况下在开始战斗前准备。
示例库分离了：
- 遭遇设计
- 平衡笔记
- 活动遭遇状态
该项目不实施 D&D 规则。它提供了一个存储和检索 AI 运行场景所需的战斗上下文的地方。
## MCP 服务器
`server/` 目录包含一个用于处理 Obsidian 库的 MCP 服务器。
它公开了以下库工具：
- `list_vault_files`
- `read_vault_file`
- `search_vault`
- `write_vault_file`
- `append_vault_file`
- `replace_in_vault_file`
- `read_vault_headings`
- `find_vault_backlinks`
- `rename_vault_file`
- `suggest_context_files`
- `suggest_save_update`
第一组提供基本的库访问和 Markdown 文件操作。管道工具帮助助手识别相关上下文并准备战役存档更新。
参见 `server/README.md` 以获取现有的服务器设置说明。
## 本项目不是
本项目不是：
- 一个完整的 D&D 战役
- 一个 VTT
- 一个规则引擎
- 一个角色生成器
- 一个地下城主的替代品
- 官方 D&D 规则或手册的来源
它是一个用于 AI 辅助战役连续性的记忆框架和模板。
## 手册和参考文件
本仓库不包括官方的 D&D 手册、受版权保护的规则书或专有内容。
用户可以在其私人库中添加自己的本地参考文件。对于示例结构，请使用 `examples/example-vault/04_Manuali/`；在您自己的库中，请使用 `04_Manuali/`。
参考文件可以包括个人笔记、摘要、自定义规则、SRD 兼容材料或您允许使用的私人参考文档。
AI 仅在规则、咒语、物品、职业特性、条件、战斗程序或机械不确定性与当前情况相关时，才应查询手册和参考文件。
示例库应仅显示结构和占位符，而不显示实际的受版权保护的 manual 文本。
## 许可证
本项目在 MIT 许可证下发布。
有关详细信息，请参见 LICENSE 文件。
