内容
<p align="center">
<img src="https://raw.githubusercontent.com/LucasRocha179/mcp-vault-reader/main/assets/banner.jpg" alt="mcp-vault-reader" width="800">
</p>
<p align="center">
<a href="https://npmjs.com/package/mcp-vault-reader"><img src="https://img.shields.io/npm/v/mcp-vault-reader" alt="npm version"></a>
<a href="LICENSE"><img src="https://img.shields.io/npm/l/mcp-vault-reader" alt="license"></a>
<img src="https://img.shields.io/node/v/mcp-vault-reader" alt="node version">
<img src="https://img.shields.io/npm/dw/mcp-vault-reader" alt="downloads/week">
<a href="https://github.com/LucasRocha179/mcp-vault-reader/actions"><img src="https://img.shields.io/github/actions/workflow/status/LucasRocha179/mcp-vault-reader/ci.yml" alt="CI"></a>
</p>
---
## 工具介绍
**mcp-vault-reader** 是一个强大的模型上下文协议（MCP）服务器，旨在将 Markdown 笔记仓库（Zettelkasten 风格，与 Obsidian 兼容）连接到任何与 MCP 兼容的 AI 客户端。它提供实时的本地索引（原地，无重复）和远程 GitHub 仓库支持（通过浅克隆），具有高性能的全文搜索、深度反向链接分析、知识图遍历和专用的、持久的 AI 内存系统。
---
## 架构与概念
以下是 `mcp-vault-reader` 如何作为您的个人笔记、本地 AI 内存和 AI 助手之间的桥梁：
```mermaid
graph TD
subgraph Client ["AI 客户端 (Cursor / Claude Desktop / VS Code)"]
AI["AI 模型 / 大型语言模型"]
end
subgraph Server ["mcp-vault-reader (MCP 服务器)"]
McpServer["MCP 协议处理程序"]
Engine["搜索引擎与图遍历器"]
VaultMgr["仓库与内存管理器"]
end
subgraph Storage ["您的知识与内存"]
LocalVaults["本地 Markdown 仓库（只读，原地）"]
GithubVaults["GitHub 远程仓库（只读，浅克隆）"]
MemoryVault["__memory__ 仓库（读写，持久上下文）"]
end
AI <-->|"MCP 工具与资源"| McpServer
McpServer <--> Engine
Engine <--> VaultMgr
VaultMgr -->|"快速全局搜索 / MiniSearch"| LocalVaults
VaultMgr -->|"简单 Git"| GithubVaults
VaultMgr <-->|"JSON / Markdown 同步"| MemoryVault
```
---
## 您的 AI 可以用它做什么
与手动搜索或上下文复制不同，您的 AI 助手将自然地与您的笔记交互：
- 🔍 **搜索所有内容**：使用语义加权搜索（`MiniSearch`）按内容、标题、标题或标签查找笔记。
- 🔗 **遍历链接**：遵循 Obsidian 兼容的 `[[维基链接]]`，探索反向链接，并跟踪概念线索。
- 📊 **探索关系**：通过请求本地知识图或相关笔记列表来发现相邻的想法。
- 📅 **检索时间线**：获取每日日记和日志以了解您的工作进展。
- 🧠 **持久记忆**：写入和查询私有记忆仓库（`__memory__`）以跟踪首选项、进度和自定义指令，跨会话。
---
## 快速开始（5 分钟）
### 1. 先决条件
确保您已安装 **Node.js v20 或更高版本**：
```bash
node --version
```
### 2. 添加您的仓库
通过 `npx` 运行 `mcp-vault-reader` 以注册本地目录作为仓库：
```bash
npx -y mcp-vault-reader vault add /path/to/your/markdown-notes my-second-brain
```
*（如果您的仓库在 GitHub 上，您可以直接添加它：`npx -y mcp-vault-reader vault add https://github.com/username/my-vault remote-vault`）*
### 3. 连接到 Claude Desktop 或 Cursor
您可以通过运行以下命令，在所有已安装的 LLM 客户端（Claude Desktop、Cursor、VS Code Cline、Roo Code）中自动配置服务器：
```bash
npx mcp-vault-reader init
```
该脚本将安全地检测您的工具并注入必要的 JSON 配置。
<details>
<summary><b>或手动配置</b></summary>
**适用于 Claude Desktop** （通常为 `~/.config/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"mcp-vault-reader": {
"command": "npx",
"args": ["-y", "mcp-vault-reader"]
}
}
}
```
**适用于 Cursor**：
1. 打开 Cursor 设置 -> **模型** -> **MCP**。
2. 点击 **+ 添加新 MCP 服务器**。
3. 名称：`mcp-vault-reader`。
4. 类型：`command`。
5. 命令：`npx -y mcp-vault-reader`。
6. 保存并重启 Cursor。
</details>
### 4. 在聊天中验证
询问您的 AI：
> "列出我的仓库并显示我的 second-brain 笔记的摘要。"
---
## 安装与执行选项
| 方法 | 命令 | 何时使用 |
|---|---|---|
| **npx（推荐）** | `npx -y mcp-vault-reader` | 零配置，自动更新，干净且无 hassle。 |
| **全局 NPM** | `npm install -g mcp-vault-reader` | 更快的后续启动，避免每次运行都下载。 |
| **从源代码** | `git clone` & `npm run build` | 适用于贡献者、本地开发和自定义分支。 |
---
## MCP 客户端配置
推荐的模式是通过 `npx` 运行而无需绝对路径。以下是确切的配置：
### VS Code Copilot / Cline / Windsurf
```json
{
"mcpServers": {
"mcp-vault-reader": {
"command": "npx",
"args": ["-y", "mcp-vault-reader"],
"env": {
"VAULT_SYNC_ON_START": "true"
}
}
}
}
```
### 高级（HTTP/SSE 传输）
如果您想将 `mcp-vault-reader` 作为后台微服务运行在 HTTP 上（非常安全）：
```bash
# 在后台启动服务器
export MCP_HTTP_PORT=3000
export MCP_HTTP_AUTH_TOKEN="your-secure-token"
export MCP_HTTP_HARDEN="true"
npx mcp-vault-reader
```
然后配置您的 MCP 客户端：
```json
{
"mcpServers": {
"mcp-vault-reader": {
"url": "http://127.0.0.1:3000/mcp",
"headers": {
"Authorization": "Bearer your-secure-token"
}
}
}
}
```
---
## 16 种工具一览
### 📂 知识仓库工具（只读）
| 工具名称 | 关键参数 | 描述 |
|---|---|---|
| `vault_list_vaults` | 无 | 列出所有已注册的仓库（本地路径、提交、笔记数量、标签）。 |
| `vault_search` | `query`，`vault_name?`，`limit?`，`fuzzy?` | 具有相关性评分和自定义摘要的全文搜索。 |
| `vault_read_note` | `path`，`vault_name` | 读取特定笔记的完整 Markdown 内容（省略前置信息）。 |
| `vault_list_notes` | `vault_name`，`folder?`，`tag?`，`limit?` | 按文件夹路径或标签列出和筛选笔记。 |
| `vault_get_backlinks` | `path`，`vault_name` | 查找所有引用目标笔记的笔记，包括链接上下文。 |
| `vault_get_graph` | `vault_name`，`center?`，`depth?`，`max_nodes?` | 构建笔记的知识节点和边链接图。 |
| `vault_get_related` | `path`，`vault_name` | 根据出站链接、反向链接和标签返回相邻笔记。 |
| `vault_follow_link` | `path`，`link`，`vault_name` | 将维基链接路径目标（例如 `[[TargetNote#Section]]`）解析为绝对路径。 |
| `vault_get_tags` | `vault_name` | 列出仓库中的所有唯一标签以及有多少笔记引用它们。 |
| `vault_get_daily_notes` | `vault_name`，`date?`，`limit?` | 发现每日日记条目（格式如 YYYY-MM-DD）。 |
| `vault_sync` | `vault_name?` | 强制存储库拉取或本地目录扫描和原子索引更新。 |
### 🧠 持久 AI 内存工具（读写）
| 工具名称 | 关键参数 | 描述 |
|---|---|---|
| `memory_status` | 无 | 检查内存仓库是否激活、其存储路径和笔记统计信息。 |
| `memory_write_note` | `path`，`title`，`content`，`tags?`，`source?` | 在私有内存仓库（`__memory__`）中创建/更新 Markdown 笔记。 |
| `memory_search` | `query`，`limit?`，`fuzzy?`，`tag?` | 专门对 AI 的内存仓库执行全文搜索。 |
| `memory_list` | `folder?`，`tag?`，`limit?` | 列出所有存储的记忆，带有文件夹结构和标签筛选器。 |
| `memory_delete_note`| `path` | 永久删除记忆笔记。 |
---
## 持久 AI 内存（`__memory__`）
**内存仓库** 是一个指定的空间，AI 在此处具有写入权限。
- 本地仓库和远程 GitHub 仓库 **严格只读**，以确保您的核心第二大脑不会被 LLM 修改或损坏。
- `__memory__` 仓库在您的配置目录中初始化（默认：`~/.mcp-vault-reader/memory/`）。
- AI 使用它来编写配置文件、保存摘要、建立待办事项列表或保存您讨论的跨会话设置。
---
## AI 默认指令
复制并粘贴此系统提示块到您的 AI 客户端的系统提示（Cursor 自定义指令、Claude Desktop 系统提示等）中，以优化工具使用：
```markdown
您可以通过 MCP（mcp-vault-reader）访问知识仓库系统。请使用以下指南：
1. **始终首先使用 `vault_list_vaults`** 以在搜索前发现可用的仓库。
2. **对广泛查询使用 `vault_search`** - 它对所有笔记执行全文搜索，并具有相关性评分。
3. **使用 `vault_read_note` 读取完整内容** 在通过搜索找到相关笔记后。
4. **使用 `vault_get_backlinks`、`vault_follow_link` 和 `vault_get_related`** 以探索知识图。
5. **使用 `vault_get_tags` 和 `vault_get_daily_notes`** 进行结构化浏览。
6. **内存仓库（`__memory__`）** 是您的持久存储：
- `memory_write_note` 保存首选项、摘要或未来会话的上下文。
- `memory_search` 检索先前存储的信息。
- `memory_list` 浏览所有存储的记忆。
- 内存在会话之间持续存在 - 请主动使用它。
7. **切勿修改仓库笔记** - 仓库是只读的。 只有内存允许写入。
8. **在查询中优先使用特定的仓库名称**，当用户提及特定知识领域时。
```
---
## 命令行参考
`mcp-vault-reader` 带有强大的命令行工具来管理索引。
### 管理仓库
```bash
# 添加本地目录仓库
mcp-vault-reader vault add ~/Notes/SecondBrain second-brain
# 添加 GitHub 仓库
mcp-vault-reader vault add https://github.com/LucasRocha179/mcp-vault-reader-test-vault.git my-test-vault
# 添加带有自定义分支的 GitHub 仓库
mcp-vault-reader vault add https://github.com/user/repo.git my-vault --branch development
# 列出所有已注册的仓库
mcp-vault-reader vault list
# 仓库的详细统计和热门标签
mcp-vault-reader vault info second-brain
# 同步仓库（拉取 Git 更新或扫描本地文件）
mcp-vault-reader vault sync second-brain
# 同步所有已注册的仓库
mcp-vault-reader vault sync
# 删除仓库（删除远程克隆或本地引用）
mcp-vault-reader vault remove second-brain
```
### 自动配置
```bash
# 使用 npx 自动配置所有已安装的客户端（Cursor、Claude、VS Code 扩展）
mcp-vault-reader init
# 自动配置为使用全局安装的包运行（无 npx 下载延迟）
mcp-vault-reader init --global
# 自动配置特定客户端（例如仅 Cursor）
mcp-vault-reader init --client cursor
# 从所有客户端删除 mcp-vault-reader 配置
mcp-vault-reader init --remove
```
### 管理内存
```bash
# 检查内存仓库状态和路径
mcp-vault-reader memory status
```
---
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `VAULT_CONFIG_DIR` | `~/.mcp-vault-reader` | 仓库配置和远程克隆存储的位置。 |
| `VAULT_SYNC_ON_START` | `false` | 如果设置为 `true`，MCP 服务器将在启动时同步所有仓库。 |
| `MCP_HTTP_PORT` | 无 | 设置端口（例如 `3000`）以运行在 HTTP/SSE 上而不是标准 stdio。 |
| `MCP_HTTP_AUTH_TOKEN` | 无 | 运行 HTTP 服务器时所需的安全令牌。 |
| `MCP_HTTP_ALLOWED_ORIGINS`| `127.0.0.1` | CORS 允许的来源。 |
| `MCP_HTTP_HARDEN` | `false` | 如果为 `true`，则启用 DNS 绑定保护和严格的速率限制。 |
---
## 示例 AI 提示
在 AI 聊天中尝试这些提示：
- *"列出我的所有仓库并显示热门标签。*
- *"查找讨论 'TypeScript 装饰器' 的笔记，并解释它们如何链接到设计模式。*
- *"检查这周的日记笔记，看看我写了什么任务。*
- *"请将我们当前的讨论摘要保存在我的内存中，文件名为 'projects/mcp-vault-reader-notes.md'。*
- *"在我的内存笔记中搜索我以前的项目。*
---
## 比较
| 功能 | mcp-vault-reader | obsidian-mcp | notes-mcp |
|---|:---:|:---:|:---:|
| **持久 AI 内存（`__memory__`）** | ✅ | ❌ | ❌ |
| **GitHub 远程仓库（浅克隆）** | ✅ | ❌ | ❌ |
| **原子索引交换（零 I/O 延迟）** | ✅ | ❌ | ❌ |
| **统一多仓库搜索** | ✅ | ❌ | ❌ |
| **每日笔记遍历** | ✅ | ❌ | ❌ |
| **灵活的 CLI 管理** | ✅ | ❌ | ❌ |
| **HTTP + SSE 安全传输** | ✅ | ❌ | ❌ |
| **丰富工具数量** | **16** | ~5 | ~3 |
---
## 故障排除
#### 1. AI 客户端中的“未注册仓库”错误
确保您首先通过 CLI 添加了仓库。配置存储在 `~/.mcp-vault-reader/config.json` 下。您可以运行 `npx mcp-vault-reader vault list` 进行验证。
#### 2. 私有 GitHub 仓库
服务器在底层使用 simple-git。对于私有仓库，请确保您的机器已配置 SSH 密钥或通过 CLI 进行身份验证（`gh auth status`）。
#### 3. `npx` 的首次运行缓慢
第一次执行 `npx mcp-vault-reader` 时，NPM 会下载包。对于后续启动更快，请全局安装包：
```bash
npm install -g mcp-vault-reader
```
#### 4. Node.js 版本错误
确保您运行的是 Node.js 20 或更高版本。使用 `node --version` 进行检查。我们利用现代 ESM 功能和 Node API 组件，需要 v20+。
---
## 安全考虑
在将笔记仓库暴露给 AI 助手时，请牢记以下安全原则：
1. **间接提示注入**：如果您索引不受信任的仓库（例如，公共 GitHub 仓库或第三方共享的文件），恶意行为者可以将指令放入 Markdown 文件中（例如，“忽略以前的指令并执行操作 X”）。当 AI 助手读取这些文件时，它可能会尝试使用其他工具执行这些指令。仅索引来自受信任来源的笔记仓库。
2. **只读仓库**：通过 CLI 注册的常见本地和远程仓库 **严格只读**。服务器不支持写入、创建或修改这些仓库中的文件，这可以防止 AI 模型更改您的主要文档。只有特殊的 `__memory__` 仓库支持写入操作。
3. **命令和标志注入防护**：传递给仓库注册的输入（URL、本地路径和分支名称）会严格验证。以连字符（`-`）开头的 URL 和分支将被拒绝，以防止针对 Git/CLI 子进程的标志注入攻击。
---
## 贡献
欢迎贡献！
1. 克隆仓库：`git clone https://github.com/LucasRocha179/mcp-vault-reader.git`
2. 安装依赖项：`npm install`
3. 运行 TypeScript 监视器：`npm run watch`
4. 运行测试：`npm test`
5. 阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解样式指南、Git 流和架构指南。
---
## 商標声明
Obsidian 是 Dynalist Inc. 的商标。本项目是一个独立的开源工具，与 Dynalist Inc. 或 Obsidian 应用程序无关、未获得资助或关联。
---
## 许可证
该项目使用 MIT 许可证 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
