内容
<div align="center">
<img src="tray/assets/icon.svg" width="80" alt="VaultGate" />
# VaultGate
**您的 Obsidian 知识库，任何 AI 助手都可访问 — 本地、私有，无需插件。**
[](https://www.npmjs.com/package/obsidian-vaultgate-mcp)
[](LICENSE)
[](https://nodejs.org)
[](https://github.com/mkemeter/obsidian-vaultgate-mcp/actions/workflows/ci.yml)
</div>
VaultGate 是一个本地 [模型上下文协议](https://modelcontextprotocol.io) 服务器，它连接任何兼容 MCP 的 AI 客户端与您的 Obsidian 知识库 — 基于 Obsidian 的原生集成 API。无需社区插件，无需云中继，无需 API 密钥。
您可以要求您的 AI 读取笔记，运行全文或语义搜索，管理任务，应用模板，编写内容，并在 Obsidian 界面中直接打开任何内容。每一次写入操作都经过 dry-run 预览，这样您就可以控制实际发生的变化。
<div align="center">
[](#托盘伴侣应用)
[](#无头npm包)
</div>
---
## ✨ 功能
<table>
<tr>
<td width="50%">
**🔒 私有设计**
笔记内容永远不会离开您的机器。仅绑定到 `127.0.0.1` — 无法从网络上的其他主机访问。
</td>
<td width="50%">
**🤖 任意 MCP 客户端**
Claude、Cursor、Windsurf、Zed 以及其他所有支持 MCP 的客户端 — 通过 HTTP 或 stdio。
</td>
</tr>
<tr>
<td>
**🔌 无需插件**
完全基于 Obsidian 的内置 CLI API。无需社区插件，无需在 Obsidian 中进行额外安装。
</td>
<td>
**🔍 离线语义搜索**
按含义查询您的知识库，而不仅仅是关键词。由 `@xenova/transformers` 提供支持 — 完全本地，无需网络调用。
</td>
</tr>
<tr>
<td>
**✋ 显式写入同意**
每次写入都是两步预览 + 确认。永远不会在未经确认的情况下修改文件。
</td>
<td>
**🪟 GUI 导航**
在 Obsidian 中直接打开任何笔记、搜索结果或每日笔记。AI 可以在 UI 中移交工作。
</td>
</tr>
<tr>
<td>
**🔐 Obsidian 保持控制**
AI 永远不会直接触摸您的文件。每次操作都由正在运行的 Obsidian 实例进行中介。
</td>
<td>
**📋 知识库约定**
在您的知识库根目录下放置一个 `VAULTGATE.md` 文件 — 自动注入到每个 AI 会话中，以便 AI 始终了解您的结构。
</td>
</tr>
</table>
---
## 目录
- [快速入门](#-快速入门)
- [无头 npm 包](#无头npm包)
- [安装](#安装)
- [连接您的 AI 客户端](#连接您的AI客户端)
- [登录时自动启动](#登录时自动启动)
- [卸载](#卸载)
- [配置](#配置)
- [可用工具](#可用工具)
- [故障排除](#故障排除)
- [托盘伴侣应用](#托盘伴侣应用)
- [平台](#平台)
- [安装](#安装-1)
- [首次运行](#首次运行)
- [连接 AI 客户端](#连接AI客户端)
- [首选项](#首选项)
- [智能搜索](#智能搜索)
- [日志](#日志)
- [退出和卸载](#退出和卸载)
- [隐私和安全](#隐私和安全)
- [仓库布局](#仓库布局)
- [贡献](#贡献)
---
## 🚀 快速入门
VaultGate 以两个发行版提供，它们共享相同的 MCP 服务器核心。请选择一个 — 您不需要两者。
| | 📦 无头 npm 包 | 🖥️ 托盘伴侣应用 |
|---|---|---|
| **最适合** | Claude Code、无头服务器、Linux、脚本 | 在 macOS 上日常使用，具有 GUI |
| **安装** | `npm install -g obsidian-vaultgate-mcp` | DMG 拖放 |
| **UI** | 无 — CLI / 守护进程 | 菜单栏图标 |
| **自动启动** | launchd / systemd / 任务调度器 | 托盘菜单中切换 |
| **智能搜索模型** | 使用时下载 | 预打包，完全离线 |
| **macOS** | ✅ | ✅ 仅限 Apple Silicon |
| **Windows** | ✅ | ❌ |
| **Linux** | ✅ | ❌ |
| **软件包大小** | ~6 MB + 延迟模型 | ~200 MB DMG |
> [!NOTE]
> 所有路径均需要 **Obsidian 1.8.9 或更高版本**。npm 包还要求 **Node.js 18+**。
### 开始前
这两个步骤适用于两个发行版。
#### 1. 注册 Obsidian CLI
CLI 与 Obsidian 捆绑在一起，但必须在使用前注册一次。
1. 打开 Obsidian → **设置 → 常规**
2. 滚动到 **命令行界面**
3. 点击 **注册 CLI**
这会写入一个套接字/管道条目，VaultGate 使用它与正在运行的 Obsidian 实例进行通信。它在重启后持续存在 — 每个机器只需一次性设置。
#### 2. (可选) 创建知识库约定
在您的知识库根目录中创建一个名为 `VAULTGATE.md` 的文件，以记录您的知识库组织结构。其内容将自动注入到 AI 助手的系统提示中 — 这样它就始终了解您的文件夹结构、命名规则、标签分类、前置元数据架构和模板约定，而无需您每次都解释它们。
**示例 `VAULTGATE.md`：**
```markdown
# 知识库约定
## 文件夹结构
- `Projects/` — 一个项目一个笔记，状态在前置元数据中
- `People/` — 联系人和团队成员
- `Daily/` — 每日笔记 (YYYY-MM-DD.md)
- `Resources/` — 参考资料
## 前置元数据
所有笔记都应具有：`status`, `tags`, `created` (ISO 日期)。
## 标签
优先使用小写 kebab-case。核心分类：#project, #person, #resource, #meeting.
## 命名
笔记标题使用句子大小写。除了连字符外，不使用特殊字符。
```
您还可以询问您的 AI 助手： *"帮助我设置知识库约定"* — 它将使用 `vault_context_set` 工具为您分析知识库结构并草拟 `VAULTGATE.md`。
> [!NOTE]
> `VAULTGATE.md` 在连接时读取。要在会话中途更新，请让您的助手调用 `vault_context` — 它始终读取当前文件内容。
---
## 💬 您能问什么？
连接后，与您的知识库自然对话。以下是涵盖主要功能的几个示例：
**查找和检索笔记**
> *"我写了什么关于 Q3 计划会议的内容？*"
> *"查找所有带有 #meeting 标签的笔记并列出它们的标题。*"
**读取笔记**
> *"读取我名为 '架构决策' 的笔记。*"
**创建和编辑**
> *"使用会议模板为今天创建名为 '与 Anna 开会' 的会议笔记。*"
> *"将此对话的摘要追加到我的 '项目创意' 笔记中。*"
**每日笔记和任务**
> *"今天的每日笔记中有哪些任务仍未完成？*"
> *"在今日笔记中添加一个行动项：跟进团队截止日期为周五。*"
**知识库范围的任务概览**
> *"显示我知识库中所有待处理的任务。*"
**发现和链接**
> *"哪些笔记链接到我的 '团队结构' 笔记？*"
> *"查找与我的 '入职计划' 类似的笔记。*"(需要智能搜索)
**移交给 Obsidian UI**
> *"打开今日的每日笔记。*"
> *"打开我的 '架构决策' 笔记并滚动到风险部分。*"
有关功能列表，请参阅 [可用工具](#可用工具)。
---
## 无头 npm 包
参考发行版 — 在 macOS、Linux 和 Windows 上运行，无 GUI。适用于 [Claude Code](#claude-code) stdio 集成、无头服务器和脚本化设置。
### 安装
```bash
npm install -g obsidian-vaultgate-mcp
```
尝试安装而无需全局安装：
```bash
npx obsidian-vaultgate-mcp
```
### 连接您的 AI 客户端
#### HTTP 客户端
启动 VaultGate：
```bash
obsidian-vaultgate-mcp
```
适用于特定知识库：
```bash
OBSIDIAN_VAULT="我的知识库" obsidian-vaultgate-mcp
```
```
✓ VaultGate 运行于 http://127.0.0.1:3001
可流式 HTTP：POST http://127.0.0.1:3001/mcp
SSE（旧版）：GET http://127.0.0.1:3001/sse
健康检查：GET http://127.0.0.1:3001/health
```
验证它是否正在运行：
```bash
curl http://localhost:3001/health # 应该打印：OK
```
在您的 AI 应用中添加新的 MCP 服务器：
| 传输方式 | URL |
|-----------|-----|
| 流式 HTTP（推荐） | `http://localhost:3001/mcp` |
| SSE 旧版 | `http://localhost:3001/sse` |
#### Claude Code
添加到 `~/.claude/settings.json`：
```json
{
"mcpServers": {
"obsidian": {
"command": "obsidian-vaultgate-mcp",
"env": {
"OBSIDIAN_VAULT": "我的知识库"
}
}
}
}
```
Claude Code 通过 stdio 管理进程生命周期 — 无需单独启动。省略 `env` 如果您只有一个知识库。
### 登录时自动启动
#### macOS (launchd)
```bash
bash "$(npm root -g)/obsidian-vaultgate-mcp/deploy/install.sh"
```
在 `~/Library/LaunchAgents/` 下安装一个 `launchd` 代理，该代理在登录时启动 VaultGate，并在失败时重启。安装脚本会自动解析所有路径（与 nvm、Homebrew、系统 Node 兼容）。
#### Linux (systemd 用户服务)
```bash
bash "$(npm root -g)/obsidian-vaultgate-mcp/deploy/install.sh"
```
在 `~/.config/systemd/user/` 下安装一个 systemd 用户服务，该服务在登录时启动 VaultGate，并在失败时重启。安装脚本会自动解析所有路径（与 nvm、volta、系统 Node 兼容）。
#### Windows（任务调度器）
```powershell
powershell -ExecutionPolicy Bypass -File "$(npm root -g)\obsidian-vaultgate-mcp\deploy\install.ps1"
```
自动检测路径，提示您输入知识库名称，编写启动包装器，并注册一个在登录时运行 VaultGate 的任务调度器任务。
### 卸载
#### macOS 和 Linux
```bash
bash "$(npm root -g)/obsidian-vaultgate-mcp/deploy/uninstall.sh"
```
停止后台服务（如果已安装），删除 npm 包，并删除本地嵌入式缓存。
#### Windows
```powershell
powershell -ExecutionPolicy Bypass -File "$(npm root -g)\obsidian-vaultgate-mcp\deploy\uninstall.ps1"
```
#### 删除的内容
| 项目 | 自动删除 |
|------|-----------------------|
| launchd 代理（macOS） | ✓ 如果已安装 |
| systemd 服务（Linux） | ✓ 如果已安装 |
| 任务调度器任务 + 包装器（Windows） | ✓ 如果已安装 |
| npm 包 + 二进制文件 | ✓ 始终 |
| 嵌入式缓存（`~/.cache/obsidian-vaultgate-mcp/`） | ✓ 始终 |
| ONNX 模型缓存（`~/.cache/huggingface/`） | 否 — 可能与其他工具共享 |
| `VAULTGATE.md` 在您的知识库中 | 否 — 您的文件，如有需要可手动删除 |
### 配置
所有配置均通过环境变量进行。单知识库设置在默认端口上不需要任何配置项。
| 变量 | 默认值 | 描述 |
|---|---|---|
| `OBSIDIAN_VAULT` | _(最后打开的知识库)_ | 目标知识库名称（目录名称，不是路径）。多个知识库打开时需要。 |
| `OBSIDIAN_MCP_PORT` | `3001` | HTTP 模式的 TCP 端口。 |
| `OBSIDIAN_MCP_TRANSPORT` | _(自动检测)_ | `http` 强制 HTTP 模式，`stdio` 强制 stdio。根据 `stdin.isTTY` 自动检测。 |
| `OBSIDIAN_CLI_PATH` | `obsidian` | Obsidian 二进制文件的绝对路径。在服务上下文中 `PATH` 与用户 shell 不同时需要。 |
### 可用工具
VaultGate 提供了 34 个基本工具，分为四个类别，以及使用时提供 5 个语义搜索工具。
#### GUI 导航
将 `obsidian://` URI 通过 OS 调度到运行的 Obsidian 实例中。带来 Obsidian 到前台 — 不读取或写入知识库数据。
| 工具 | 描述 |
|---|---|
| `note_open` | 在 Obsidian GUI 中打开笔记。接受 `path=`（知识库根目录）或 `file=`（wikilink 名称）；可选 `heading` 或 `block` 以滚动到某个位置 |
| `search_open` | 打开 Obsidian 搜索面板并预填充查询 |
| `daily_open` | 在 Obsidian GUI 中打开今日的每日笔记 |
#### 只读
| 工具 | 描述 |
|---|---|
| `files_list` | 列出知识库中的所有笔记 |
| `files_read` | 读取笔记的全文内容 |
| `search` | 知识库范围的全文搜索 |
| `daily_read` | 读取今日的每日笔记 |
| `tasks_all` | 所有任务（已完成和未完成） |
| `tasks_pending` | 仅限未完成的任务 |
| `tasks_daily` | 今日每日笔记中的未完成任务 |
| `templates_list` | 列出可用的模板（需要核心模板插件 - 参见下面的注释） |
| `property_read` | 按名称读取特定的 YAML 前置元数据属性 |
| `tags` | 知识库范围内的所有标签 |
| `backlinks` | 链接到给定笔记的笔记 |
| `unresolved` | 指向不存在的笔记的 wikilinks |
| `plugins_list` | 已安装的社区插件 |
| `dev_errors` | Obsidian 控制台的最新错误 |
| `dev_console` | Obsidian 的控制台日志输出（需要先运行 `dev:debug on`） |
| `dev_css` | 计算出的 CSS 适用于 DOM 选择器 |
| `dev_dom` | Obsidian 窗口的 DOM 子树 |
| `vault_context` | 从 `VAULTGATE.md` 读取知识库约定（如果约定未在会话开始时传递） |
#### 写（默认 dry-run）
每个写入工具默认 `dryRun=true` — AI 显示更改的预览，并在修改任何文件之前等待显式确认。
| 工具 | 描述 |
|---|---|
| `note_create` | 创建新笔记（使用 `path=` 用于子文件夹位置） |
| `note_append` | 在现有笔记中追加内容 |
| `note_prepend` | 在现有笔记中prepend 内容 |
| `note_update` | 替换现有笔记的全部内容 |
| `note_trash` | 将笔记移动到系统垃圾箱（可恢复） |
| `daily_append` | 追加内容到今日的每日笔记 |
| `templates_apply` | 将模板应用于笔记 |
| `property_set` | 设置或更新 YAML 前置元数据属性 |
| `plugin_reload` | 通过 ID 重载社区插件 |
| `dev_screenshot` | 捕获 Obsidian 窗口的截图 |
| `dev_mobile` | 切换移动视口仿真线模式 |
| `eval` ⚠️ | 在 Obsidian 渲染器中执行任意 JavaScript - 请仔细审查后再批准 |
| `vault_context_set` | 创建或更新 `VAULTGATE.md` - AI 助手在会话开始时读取的知识库约定文件 |
> [!NOTE]
> **templates_list / templates_apply** 需要 Obsidian 内置的 **模板** 核心插件，并在其设置中配置文件夹。如果您的知识库使用 **Templater** 社区插件（或禁用核心插件），这些工具将返回 `Error: No template folder configured`。这是配置依赖项，而不是错误。
#### 语义搜索
当 `@xenova/transformers` 可用（作为可选依赖项安装）时，会自动注册另外五个工具：
- `semantic_search` - 按含义查询，返回具有相关性得分和匹配章节标题的排名结果
- `find_similar` - 查找与给定路径类似的笔记
- `vault_info` - 索引状态和笔记数量
- `index_vault` - 重新嵌入已更改的笔记，而不丢弃现有的缓存（例行重索引）
- `clear_index` - 仅当缓存文件损坏时删除缓存文件并从头开始重建；请在使用前使用 `index_vault`**不要使用 `index_vault`** - `index_vault` 已经处理了增量更新而不会导致数据丢失。
嵌入式模型 (`bge-small-en-v1.5`, ~100 MB) 下载到 `~/.cache/huggingface/`。所有后续操作均完全离线。如果 `@xenova/transformers` 无法在当前平台加载，VaultGate 将正常启动，带有基本工具集 - 无需配置更改。
> [!WARNING]
> `@xenova/transformers` 包依赖于 `onnxruntime-web`，后者依赖于 `protobufjs` v6.x。protobufjs 的 v6.x 分支有 [已知漏洞](https://github.com/protobufjs/protobuf.js/security/advisories)。您的知识库内容永远不会发送到网络 - 唯一的外部流量是一次性的模型下载路径，来自 HuggingFace。风险仅限于下载路径，继承自供应链；它无法从此软件包中修补，直到上游更新。
### 故障排除
**`command not found: obsidian-vaultgate-mcp`**
`npm` 全局 bin 目录不在 `PATH` 上。运行 `npm bin -g` 查找它，然后添加到 shell 配置文件。或者，通过 `npx obsidian-vaultgate-mcp` 调用。
**`command not found: obsidian`（CLI 二进制文件）**
CLI 未注册。请参阅上面的 [注册 Obsidian CLI](#1-注册obsidian-cli)。
**服务器启动但 AI 客户端报告没有工具**
客户端有一个过时的会话。断开并重新连接以触发新的 `initialize` 握手。
**`semantic_search` 返回“仍在索引中”**
嵌入式索引在启动时异步构建。对于大型知识库，这可能需要几分钟。`vault_info` 显示当前索引状态。
**端口已被占用**
设置 `OBSIDIAN_MCP_PORT=3002` 并在您的 AI 客户端中更新 URL。
**Obsidian 在登录时启动**
这不再发生。启动健康检查仅验证 CLI 二进制文件是否存在于磁盘上 - 它不会执行 Obsidian。如果您发现 Obsidian 在登录时启动，请在系统设置中检查您的登录项目。
**`note_open` / `search_open` / `daily_open` 带来 Obsidian 到前台**
这是故意的 - 这些工具旨在将工作交给您在 UI 中。
**`xdg-open: command not found` (Linux)**
通过您的包管理器安装 `xdg-utils`（例如 `sudo apt install xdg-utils`）以启用 URI 调度。
---
## 托盘伴侣应用程序
一个菜单栏应用程序，它在原生 macOS GUI 中封装了相同的 VaultGate MCP 服务器核心 - 不需要终端。它公开了 [相同的 34 + 5 个工具](#available-tools)，并在上面添加了一层 GUI 便利：
<div align="center">
[](https://github.com/mkemeter/obsidian-vaultgate-mcp/releases/latest)
</div>
<table>
<tr>
<td width="50%">
**📊 一目了然的菜单栏状态**
托盘图标显示服务器状态 - 运行、索引、错误 - 无需打开终端。
</td>
<td width="50%">
**🔍 预打包的智能搜索**
嵌入模型（~34 MB）内置于应用程序中。完全离线 - 无需下载，无需网络调用。
</td>
</tr>
<tr>
<td>
**🔗 一键连接 URL**
单击一次即可将 `http://127.0.0.1:3001/mcp` 复制到剪贴板并粘贴到任何 AI 客户端中。
</td>
<td>
**🚀 登录时打开**
原生 macOS 登录项目注册。无需 `launchctl` 调整 - 只需切换开关。
</td>
</tr>
<tr>
<td>
**📋 两步查看日志**
服务器 stdout/stderr 转发到旋转日志文件。单击一次菜单即可打开。
</td>
<td>
**⚙️ 完整的首选项窗口**
库选择器、端口、Obsidian 二进制路径 - 全部在 UI 中。无需手动编辑配置文件。
</td>
</tr>
</table>
### 平台
| 平台 | 托盘伴侣 | 无头 npm 包 |
|----------|----------------|----------------------|
| macOS (Apple Silicon) | ✅ DMG | ✅ |
| macOS (Intel) | ❌ | ✅ |
| Windows | ❌ | ✅ |
| Linux | ❌ | ✅ (`deploy/systemd/`) |
### 安装
1. 从 [最新版本](https://github.com/mkemeter/obsidian-vaultgate-mcp/releases/latest) 下载 `VaultGate-X.Y.Z-mac-arm64.dmg`。
2. 打开 DMG 并将 **VaultGate** 拖入 `Applications`。
3. **绕过 Gatekeeper**（应用程序未签名 - 参见下面的 [代码签名](#code-signing)）：
> [!WARNING]
> 在 macOS 15.1 及更高版本中，Apple 删除了“无论如何打开”GUI 按钮。在启动前在终端中运行以下命令：
>
> ```bash
> xattr -r -d com.apple.quarantine /Applications/VaultGate.app
> ```
>
> 在旧版 macOS 中，您可以右键单击 → 打开应用程序并在对话框中单击“打开”。
4. 从应用程序启动 VaultGate。托盘图标出现在菜单栏中。
### 首次运行
启动 VaultGate 时：
1. **自动检测 Obsidian.** 它探测标准安装路径 (`/Applications/Obsidian.app/Contents/MacOS/obsidian`)。
2. **自动检测您的库.** 它读取 Obsidian 的 `obsidian.json` 以枚举已注册的库。如果恰好有一个库注册，则该库将被静默选择。如果存在多个库，则使用活动库（您可以从首选项中固定特定库）。
3. **在 `http://127.0.0.1:3001/mcp` 上启动捆绑的 MCP 服务器**。
4. **在后台开始索引** 以用于智能搜索。托盘菜单显示“○ 构建索引（N/M）…”，然后变为“✓ 智能搜索就绪 - N 条笔记”。当此操作完成时，会触发一个原生通知。
如果出现问题，托盘图标菜单会显示故障模式：
| 菜单显示 | 操作 |
|------------|------------|
| `○ Obsidian 未找到` | 点击 **首选项…** 并使用 **浏览…** 定位 Obsidian 的二进制文件。 |
| `○ Obsidian CLI 未注册` | 在 Obsidian 中：**设置 → 常规 → 命令行界面 → 注册 CLI**，然后在托盘菜单中点击 **启动**。 |
| `○ 错误 - 端口被占用` | 打开 **首选项…** 并更改端口（默认 `3001`）。常见冲突：另一个 VaultGate 实例、不同的 MCP 服务器。 |
| `○ 错误 - 服务器崩溃` | 点击 **打开日志…** 并检查文件底部。服务器重试，指数级退避（1s → 2s → 4s），最多三次快速崩溃，然后放弃。 |
### 连接 AI 客户端
托盘图标显示 `● 运行 - <库名称>` 后：
1. 点击托盘图标 → **复制连接 URL**。
2. 将 `http://127.0.0.1:3001/mcp` 粘贴到客户端的 MCP 配置中：
- **Cursor / Windsurf / Zed**：将其添加为可流式 HTTP MCP 服务器。
- **Claude Code**：优先使用 npm 包 + stdio 传输（参见上面的 [Claude Code](#claude-code)）。
URL 永远不会离开 `127.0.0.1` - 它绑定到 localhost 并拒绝其他来源。
### 首选项
通过托盘菜单 → **首选项…** 打开。
| 字段 | 功能 |
|-------|--------------|
| **库** | Obsidian 注册的库下拉列表。选择特定库或保留 **活动库（默认）** 以使用 Obsidian 中当前聚焦的库。 |
| **本地服务器端口** | VaultGate 绑定的 HTTP 端口。默认为 `3001`。如果另一个进程占用该端口，请更改此设置。 |
| **Obsidian 二进制文件** | 自动检测；如果您的安装位于非标准位置，请使用 **浏览…** 进行覆盖。 |
| **登录时打开 VaultGate** | 原生 macOS 登录项目注册（系统设置 → 常规 → 登录项目）。 |
保存任何更改 **重启服务器**，使新设置立即生效。
### 智能搜索
托盘应用程序随附 [`Xenova/bge-small-en-v1.5`](https://huggingface.co/Xenova/bge-small-en-v1.5) 嵌入模型（~34 MB）。在首次启动时：
- 模型从捆绑包中加载 - **无需下载，无需网络调用**。
- 后台作业逐一嵌入库笔记。进度在托盘菜单中显示（`○ 构建索引（142/523）…`）。
- 所有 34 个基本工具在整个过程中都有效 - 只有 5 个语义工具（`semantic_search`、`find_similar`、`index_vault`、`vault_info`、`clear_index`）等待索引。
索引首次达到“就绪”时，会触发一次性原生通知。然后状态保持一致：后续重启从 `~/.cache/obsidian-vaultgate-mcp/` 中检索缓存的索引。
如果索引卡住或您频繁切换库，请从 AI 客户端运行 `clear_index` 以清除缓存并从头开始重建。
### 日志
托盘菜单中的 **打开日志…** 打开 `vaultgate.log` 文件：
| 平台 | 日志文件 |
|----------|----------|
| macOS | `~/Library/Application Support/VaultGate/vaultgate.log` |
日志每 10 MB 轮换一次；最多保留三个文件（`vaultgate.log`、`.log.1`、`.log.2`）。
### 退出和卸载
- **退出**：托盘菜单 → **退出 VaultGate**。向捆绑的服务器发送 `SIGTERM`，等待最多 3 秒让正在进行的 HTTP 请求耗尽，然后退出。
- **卸载**：将 `VaultGate.app` 拖到回收站。可选地删除 `~/Library/Application Support/VaultGate/` 以删除日志和配置。
<details>
<summary>代码签名</summary>
VaultGate 的托盘应用程序 **当前未签名**。我们不提供代码签名证书，因为 Apple 开发者计划会员资格（每年 99 美元）超出了早期版本的范围。
该应用程序的受众 - 构建 MCP 集成的开发人员 - 常规处理未签名的二进制文件。权衡是一次 `xattr` 命令在首次安装时。
</details>
---
## 隐私和安全
- **仅本地执行。** 所有库操作都通过正在运行的 Obsidian 实例进行 - 永远不会直接访问文件系统。Obsidian 的内部状态（链接、索引、插件上下文）保持一致。
- **仅环回绑定。** HTTP 服务器监听 `127.0.0.1` 并且无法从网络上的其他主机访问。
- **显式写入同意。** 每个写入操作都需要两步交互：预览后确认。没有文件在单个工具调用中被修改。
- **无凭证。** 访问权限限定在本地用户会话范围内 - 无令牌、API 密钥或身份验证要求。
- **开源，共用。** GPLv3 确保源代码保持开放。准确检查在您的机器上运行的内容。
---
## 仓库布局
```
obsidian-vaultgate-mcp/
├── server/ npm 包（obsidian-vaultgate-mcp on npm）
│ ├── src/ TypeScript 源代码
│ ├── tests/ Vitest 测试套件
│ └── deploy/ launchd / systemd / Task Scheduler 安装脚本
├── tray/ VaultGate 托盘伴侣应用程序（Electron，macOS arm64）
│ ├── src/
│ ├── renderer/ 首选项窗口 HTML
│ └── assets/ 图标 + 预打包的嵌入模型
├── docs/ 共享的跨剪辑文档
│ ├── CONTRIBUTING.md
│ ├── CHANGELOG.md
│ └── SECURITY.md
└── .github/workflows/ CI（ci.yml = server，tray.yml = tray）
```
---
## 贡献
参见 [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)，了解架构概述、两种分发版本的开发设置、测试约定、代码样式和托盘特定开发人员指南。
```bash
git clone https://github.com/mkemeter/obsidian-vaultgate-mcp.git
cd obsidian-vaultgate-mcp/server
npm install
npm test
```
## 许可证
GPL-3.0-or-later。参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器