内容
# MasterVault MCP 服务器
一款无界面、基于文件系统的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，可以为 **任何 MasterVault** 提供服务——其文件 *和* 操作协议——给任何 MCP 客户端，通过标准输入输出。无需 Obsidian。
将服务器指向一个 vault 目录；任何支持 MCP 的 LLM 客户端（ModelForge、Claude Desktop、AnythingLLM 等）都可以随后定位到 vault 的协议，读取和搜索其内容，记录决策，并软删除文件——所有操作都经过客户端自己的审批流程。
## 为什么存在
Obsidian vault 已经可以通过 Local REST API 插件通过 MCP 提供服务，但这与 Obsidian 绑定了。此服务器取消了对 Obsidian 的依赖：它在普通目录上使用相同的 vault 语义，因此 MasterVault 可以移植到任何客户端和任何模型。它还提供了 vault 的 *协议*（定位、决策记录、软删除），而不只是其文件——这样，全新的 LLM 可以运行系统，而不仅仅是读取它。
## 安装
```bash
git clone <你的仓库网址> mastervault-mcp-server
cd mastervault-mcp-server
npm install # 同时通过 prepare 脚本构建
npm run build # （如果你跳过了 prepare）
```
需要 Node.js 18+。
## 运行
```bash
mastervault-mcp-server /绝对路径/到/vault
# 或
MASTERVAULT_ROOT=/绝对路径/到/vault node dist/index.js
```
vault 路径是唯一的配置。没有任何硬编码——同一个二进制文件为任何 vault 提供服务。
### 多 vault 发现
将服务器指向父目录而不是单个 vault，它会在其下发现每个 MasterVault（任何包含 `_orientation.md` 的目录）：
```bash
mastervault-mcp-server --discover /路径/到/项目根目录
```
第一个发现的 vault（按字母顺序）成为活动 vault；`mastervault_list_vaults` 工具列出所有 vault 的名称。扫描是有深度限制的，跳过隐藏和依赖目录，并且不跟随符号链接出树。发现仅 *定位* vaults——每个文件操作都保持在活动 vault 的净化根目录内，因此 vault 名称永远不能选择任意路径。
*发现功能由 [Grigori Korotkikh](https://github.com/JustMichael-80/mastervault-mcp-server) 贡献。*
### 捆绑的单文件构建
为了将服务器作为一个自包含的文件出售或交付，没有消费者端的 `npm install`:
```bash
npm run build:bundled
# 生成 dist-bundled/index.js — 所有依赖内联（约 870kb）
node dist-bundled/index.js /绝对路径/到/vault
```
捆绑包由 esbuild（Node 18 目标，ESM）使用 CommonJS 互操作的 `createRequire` 垫片生成。在另一个应用程序将此服务器作为组件打包而不是依赖于它作为已安装的模块时很有用。
## 连接客户端
### ModelForge
在 **设置 → MCP 服务器** 中，添加一个 **stdio** 服务器：
- **命令：** `node`
- **参数：** `/绝对路径/到/mastervault-mcp-server/dist/index.js` `/绝对路径/到/vault`
（或直接使用全局安装的 `mastervault-mcp-server` 二进制文件）。然后，服务器的工具出现在 Agent 模式的工具列表中，每个工具都位于 ModelForge 的允许/拒绝审批后面——就像其内置的文件工具一样。
### 任意 MCP 客户端（通用 stdio 配置）
```json
{
"mcpServers": {
"mastervault": {
"command": "node",
"args": ["/绝对路径/到/dist/index.js", "/绝对路径/到/vault"]
}
}
}
```
## 工具
| 工具 | 级别 | 只读 | 功能 |
|------|------|:---------:|--------------|
| `mastervault_orient` | 协议 | ✅ | 读取定位文件和它指向的协议文件，按顺序。 **首先调用此工具。** |
| `mastervault_get_confidence_summary` | 协议 | ✅ | 返回校准仪表盘（ `_Meta/Confidence Summary.md`）。 |
| `mastervault_log_decision` | 协议 | ✍️ | 将后果决策（提案 + 置信度 + 裁决）追加到 `_Meta/Decision Log.md` 中的正确类别。 |
| `mastervault_read` | 文件 | ✅ | 读取文件，可选地按行范围；解析 markdown frontmatter。 |
| `mastervault_list` | 文件 | ✅ | 列出目录，分页，目录优先。 |
| `mastervault_search` | 文件 | ✅ | 跨文本文件进行不区分大小写的全文搜索。 |
| `mastervault_write` | 文件 | ✍️ | 创建或覆盖文件。 |
| `mastervault_patch` | 文件 | ✍️ | 替换文件中的一个确切、唯一的文本块。 |
| `mastervault_stage_delete` | 删除 | ✍️ | 将文件移动到 `_ToDelete/` 并记录提案。 **从不硬删除。** |
| `mastervault_git_status` | git | ✅ | vault 的 Git 状态（如果在版本控制下）。 |
| `mastervault_git_log` | git | ✅ | 最近的提交。 |
| `mastervault_git_diff` | git | ✅ | 工作树或暂存的差异，可选地针对一个文件。 |
每个工具都支持 `response_format: "markdown"` （默认）或 `"json"`。三个 git 工具都是只读的；在非 git vault 上，它们返回一个清晰的“不是存储库”消息而不是错误。在 `--discover` 模式下，`mastervault_list_vaults` 也被公开。
## 安全模型
- **路径限制是唯一的安全边界。** 每个路径在进行文件系统调用之前都会被解析和限制在 vault 根目录内。词汇 `..` 遍历、绝对路径和空字节被拒绝；前导斜杠被视为 vault 相对路径，而不是文件系统绝对路径。现有路径会进行第二次 `realpath` 检查，以便 vault 内的符号链接不能指向 vault 外部。
- **无硬删除。** 服务器没有销毁数据的工具。 `stage_delete` 仅 *移动* 文件到 `_ToDelete/`；人类是唯一清空它的最终参与者。这就是为什么 `stage_delete` 被标记为非破坏性的——它通过设计是可逆的。
- **无 shell 执行。** 仅文件操作。如果客户端需要 shell 访问，它会自己提供（ModelForge 单独提供受限的、单独的沙盒）。
- **stdio 卫生。** 所有日志记录都输出到 stderr；stdout 仅携带 MCP 协议。
## MasterVault 协议层
该服务器不仅仅是一个文件服务器，因为它理解了三个约定：
- **`_orientation.md`** —— 一个全新的 LLM 首先读取的入口点（通过 `mastervault_orient`）以继承 vault 的工作规则。
- **`_Meta/Decision Log.md` + `Confidence Summary.md`** —— 一个决策记录 + 校准系统：后果提案被记录为具有预裁决置信度估计，估计和结果之间的差距累积为每个类别的校准信号。
- **`_ToDelete/`** —— 软删除暂存区；人类始终是删除的最终参与者。
缺少这些文件的 vault 仍然作为一个普通文件树工作——协议工具报告缺少的内容而不是失败。
## 开发
```bash
npm run dev # tsx 监视
npm run build # tsc -> dist/
npm run build:bundled # esbuild -> dist-bundled/index.js （单文件）
npm test # node --test, 25 个测试
npm start # node dist/index.js <vault>
```
### 测试
测试套件（`test/vault.test.mjs`，`test/tools.test.mjs`）涵盖了文件系统层、路径限制安全边界（遍历、绝对路径、空字节、符号链接逃逸）和工具层（补丁匹配拒绝、部分感知的决策记录、软删除冲突处理）。关于平台覆盖的说明：测试运行器的沙盒可能无法重现每个目标操作系统文件系统的行为（例如 macOS 符号链接规范化），因此 CI 中的绿色运行是必要的但不充分的——在部署平台上验证后，再依赖文件系统边界行为。
## 许可证
MIT
