# @bitbonsai/mcpvault 中文文档

规范地址：https://npmcn.com/package/%40bitbonsai/mcpvault/

版本：0\.18\.3
npm 元数据更新时间：2026-10-31T23:34:45.672Z
中文译文更新时间：2026-11-08T04:04:36.696Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bitbonsai/mcpvault
原文对照：https://npmcn.com/package/%40bitbonsai/mcpvault/?lang=original
项目主页：https://mcpvault.org/
源码仓库：https://github.com/bitbonsai/mcpvault

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：171 kB，42 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：4 个
- 首次发布：2026-03-12T12:29:37.684Z
- 最新版本发布：2026-10-31T23:34:45.348Z
- 近 30 天下载量：74413（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

Absidian 保险库的通用AI桥 - 连接任何兼容 MCP 的助手

## 安装

```sh
npm install @bitbonsai/mcpvault
```

也可以使用：`pnpm add @bitbonsai/mcpvault`、`yarn add @bitbonsai/mcpvault`、`bun add @bitbonsai/mcpvault`

## README

![image](https://github.com/user-attachments/assets/1e21d898-811b-42c2-a810-bf921dde0f58)

# MCPVult 错误

[![MCP Toplist](https://mcptoplist.com/badge/glama%2Fbitbonsai%2Fmcpvault.svg)](https://mcptoplist.com/server/glama%2Fbitbonsai%2Fmcpvault)

一个本地的MCP服务器,可以让兼容的客户端在一个Obsidian金库中读取,搜索,并编辑笔记. MCPVault直接与金库文件相配合,将文件操作限制在已配置的金库根上,并为未改变的前事字段保留格式.

[https://mcpvault.org (英语)](https://mcpvault.org/)

[更改日志](https://npmcn.com/package/%40bitbonsai/mcpvault/CHANGELOG.md)

[![GitHub Stars](https://img.shields.io/github/stars/bitbonsai/mcpvault?style=flat&logo=github&logoColor=white&color=9065ea&labelColor=262626)](https://github.com/bitbonsai/mcpvault) [![npm version](https://img.shields.io/npm/v/%40bitbonsai%2Fmcpvault?style=flat&logo=npm&logoColor=white&color=9065ea&labelColor=262626)](https://www.npmjs.com/package/@bitbonsai/mcpvault) [![npm downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fmcpvault.org%2Fapi%2Fdownloads.json&style=flat&logo=npm&logoColor=white&color=9065ea&labelColor=262626)](https://www.npmjs.com/package/@bitbonsai/mcpvault) [![GitHub Sponsors](https://img.shields.io/github/sponsors/BitBonsai?style=flat&logo=github&logoColor=white&color=9065ea&labelColor=262626)](https://github.com/sponsors/bitbonsai) [![Ko-Fi](https://img.shields.io/badge/Ko--fi-Support%20Me-9065ea?style=flat&logo=ko-fi&logoColor=white&labelColor=262626)](https://ko-fi.com/bitbonsai) [![Liberapay](https://img.shields.io/badge/Liberapay-Weekly%20Support-9065ea?style=flat&logo=liberapay&logoColor=white&labelColor=262626)](https://liberapay.com/bitbonsai/)

## 支助客户

Claude桌面、Claude代码、ChatGPT桌面(企业+)、OpenCode、双子座CLI、OpenAI Codex、IntelliJ EIDA 2025.1+、Cursor、Windsurf和Ontheia都有配置示例。 其他客户端如果支持本地stdio MCP服务器,可以使用MCPVault.

[https://github.com/user-attachments/assets/657ac4c6-1cd2-4cc3-829f-fd095a32f71c 互联网档案馆的存檔,存档日期2013-12-2](https://github.com/user-attachments/assets/657ac4c6-1cd2-4cc3-829f-fd095a32f71c)

## 快开始

1.  **安装节点.js运行时间 :**
    
    ```bash
    # Download from https://nodejs.org (v22.12.0 or later)
    # or use a package manager like nvm, brew, apt, etc.
    ```
    
2.  **测试服务器 :**
    
    如果使用已发布的软件包 :
    
    ```bash
    npx @modelcontextprotocol/inspector npx @bitbonsai/mcpvault@latest /path/to/your/vault
    ```
    
3.  **配置您的 AI 客户端 :**
    
    **克劳德桌面** - 复制这个给 `claude_desktop_config.json`数字 :
    
    ```json
    {
      "mcpServers": {
        "obsidian": {
          "command": "npx",
          "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"]
        }
      }
    }
    ```
    
    **克劳德代码** - 复制这个给 `~/.claude.json`数字 :
    
    ```json
    {
      "mcpServers": {
        "obsidian": {
          "command": "npx",
          "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"],
          "env": {}
        }
      }
    }
    ```
    
    **打开代码** - 复制这个给 `~/.config/opencode/opencode.json`
    
    ```json
    {
      "mcp": {
        "obsidian": {
          "type": "local",
          "command": [
            "npx",
            "@bitbonsai/mcpvault@latest",
            "/path/to/your/vault/"
          ],
          "enabled": true
        }
      }
    }
    ```
    
    替换 `/path/to/your/vault` 与你真正的欧比多金库路径.
    
    其他平台见 [详细的配置指南](https://npmcn.com/package/%40bitbonsai/mcpvault/#readme-ai-client-configuration) 见下文.
    
4.  **用你的人工智能测试:**
    
    -   "我的Abbidian金库里的资料"
    -   "读取我的笔记,叫做"项目理想"
    -   "用今天的日期创造出新的音符"

要验证连接,请您客户端列出 MCPVault 工具或读取已知的注释 .

## 如何连接

一个MCP客户端启动MCPVault作为本地的stdio进程并经过金库路径. MCPVault向每个被支持的客户端暴露出相同的工具,因此服务器没有绑定在一个AI提供者上. Obsidian不需要运行,不需要Obsidian插件.

## 特征

-   AST- 意识前题更新为未修改的 YAML 字段保留格式 .
-   路由检查块转弯, 共鸣链接出逃,点文件, `.obsidian`, (中文(简体) ), `.git`,以及 `node_modules`。 。 。 .
-   18个MCP工具覆盖注释和文件操作:
    -   文件操作 : `read_note`, (中文(简体) ), `write_note`, (中文(简体) ), `patch_note`, (中文(简体) ), `delete_note`, (中文(简体) ), `move_note`, (中文(简体) ), `move_file`
    -   部分内容如下: `get_note_outline`, (中文(简体) ), `read_note_lines`
    -   目录和批次如下: `list_directory`, (中文(简体) ), `read_multiple_notes`
    -   搜索 : `search_notes` 多字匹配和BM25重排
    -   元数据和标签 : `get_frontmatter`, (中文(简体) ), `update_frontmatter`, (中文(简体) ), `get_notes_info`, (中文(简体) ), `get_vault_stats`, (中文(简体) ), `manage_tags`, (中文(简体) ), `list_all_tags`
    -   维基链接: `wiki_link` 当名称模糊时解析名称并返回其它路径
-   `write_note` 支持覆盖、附加和预置模式.
-   `delete_note` 财务报告和审定财务报表 `move_file` 需要匹配的确认路径.
-   路径参数在验证前会修剪 .
-   搜索和批量工具默认返回压缩字段; 设置 `prettyPrint: true` 用于扩展产出.
-   套件会输出TypeScript声明和公开类型.
-   MCPVault 不需要 Obsidian 插件.

## 先决条件

-   [节点.js](https://nodejs.org/) 运行时间(v22.12.0或以后)
-   Obsidian 金库( 本地目录为 `.md`, (中文(简体) ), `.markdown`, (中文(简体) ), `.txt`, (中文(简体) ), `.base`,或 `.canvas` 文档)
-   MCP相容的AI客户端(Claude桌面,ChatGPT桌面,克洛德代码等)

## 安装

### 最终用户

`npx` 下载并运行软件包 :

```bash
npx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault
```

如果您省略了金库路径, 服务器会使用您当前的工作目录作为金库根 .

### 对于开发者

1.  克隆此寄存器
2.  使用正确的节点:

```bash
nvm use  # Uses Node 24 from .nvmrc
```

3.  安装 npm 的依赖 :

```bash
npm install  # Corepack automatically uses npm 10.9.0
```

4.  与MCP检查员进行本地测试:

```bash
npx @modelcontextprotocol/inspector npm start /path/to/your/vault
```

使用 MCP 检查器在添加到客户端之前先测试服务器 :

```bash
# Install globally for easier access
npm install -g @modelcontextprotocol/inspector

# Test with any vault
mcp-inspector npx @bitbonsai/mcpvault@latest /path/to/your/vault
```

## 使用量

### 运行服务器

**终端用户 :**

```bash
npx @bitbonsai/mcpvault@latest
npx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault
npx @bitbonsai/mcpvault@latest ./Vault
```

**开发者 :**

```bash
npm start
npm start /path/to/your/obsidian/vault
npm start ./Vault
```

### AI 客户端配置

#### 克劳德桌面

添加到您的 Claude 桌面配置文件 :

**单个默认 :**

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/MyVault"
      ]
    }
  }
}
```

**多个断层 :**

```json
{
  "mcpServers": {
    "obsidian-personal": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/PersonalVault"
      ]
    },
    "obsidian-work": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/WorkVault"
      ]
    }
  }
}
```

**只读模式 :**

添加 `--read-only` 在金库路径之后,只显示读取工具。 变异工具在发现时被省略,如果直接调用则被拒绝.

```json
{
  "mcpServers": {
    "obsidian-read-only": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/ResearchVault",
        "--read-only"
      ]
    }
  }
}
```

CLI也接受了 `--read-only true` 财务报告和审定财务报表 `--read-only=true` 用于需要明确值的配置系统。 关闭选项, 或者设置为 `false`,以保持正常的读取/写入访问.

**默认搜索和列表排除 :**

重复 `--exclude <subtree>` 来隐藏金库关联文件夹 `search_notes` 财务报告和审定财务报表 `list_directory` 在每次会议。 待命 `excludePaths` 添加到这些默认值。 直接读写工具仍然可供排除路径使用.

```json
"args": [
  "@bitbonsai/mcpvault@latest",
  "/Users/yourname/Documents/ResearchVault",
  "--exclude", "Archive",
  "--exclude", "Snapshots/Old"
]
```

MCPVault 不读 Obsidian 的 `.obsidian/app.json`;排除在 MCP 服务器配置中保持清晰.

**配置文件位置 :**

-   **马可斯:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-   **窗口 :** `C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json`
-   **林纳:** `~/.config/Claude/claude_desktop_config.json`

_您也可以通过 Claude 桌面 设置 开发者 编辑配置_

#### 聊天GPT 桌面

**所需经费:** ChatGPT 企业、教育或团队订阅(个人+用户不可用)

ChatGPT通过Deep Research and developers模式使用MCP. 配置是通过 ChatGPT 接口完成的 :

1.  访问 ChatGPT 开发者模式( β 特性)
2.  通过内置的 MCP 客户端配置 MCP 服务器
3.  为您的组织创建自定义连接符

_注:ChatGPT桌面的MCP集成目前仅限于企业订阅,使用与基于文件的配置不同的设置过程._

#### 克劳德代码

Claude 代码使用 `.claude.json` 配置文件 :

**用户范围( 建议):** 编辑 `~/.claude.json`数字 :

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"],
      "env": {}
    }
  }
}
```

**项目范围 :** 编辑 `.claude.json` 在您的项目中,或在项目中添加:

```json
{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "obsidian": {
          "command": "npx",
          "args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"]
        }
      }
    }
  }
}
```

**使用 Claude 代码 CLI :**

```bash
claude mcp add obsidian --scope user npx @bitbonsai/mcpvault /path/to/your/vault
```

#### 鹅桌面

在"鹅"桌面设置上,单击 **添加自定义扩展名**,并在命令字段上添加:

```bash
npx @bitbonsai/mcpvault@latest /path/to/your/vault
```

#### 其他MCP-兼容客户端(2025)

**确认 MCP 支持 :**

-   **2025.1+ (英语)** - 本地MCP客户支持
-   **光标 IDE** - 内置的 MCP 兼容性
-   **Windsurf IDE 风平浪静** - 全面纳入多边协商进程
-   **[欧西娅](https://ontheia.ai/)** - 自主托管、开源的AI代理平台
-   **Zed、Replit、Codeum、原始图** - 发展中
-   **微软副驾驶工作室** - 具有一击服务器连接的本地 MCP 支持

大多数现代的MCP客户端都使用相类似的JSON配置模式. 请查看您特定客户的文件 以获取确切的设置指示.

### 实例

#### 问你的人工智能助手 你的笔记:

-   "我的Absidian金库里有什么文件?"
-   "读取我的笔记,叫做"项目理想"
-   "给我看所有笔记 标题是"AI""

#### 请您的人工智能助理协助音符管理:

-   "用今天的日期在前题创作出新的笔记,叫做"会议笔记""Md"
-   "我日记的今天日记条目附录"
-   "给我的待办事宜清单准备紧急任务"
-   "在我的任务说明中添加“项目”和“紧急”标记
-   "在我的研究笔记上写下所有的标签"
-   从我完成的文章中删除"草稿"标签
-   在我的“ Projects” 文件夹中列出所有减记文件
-   "删除旧注"草案-理想.md"(附确认)"

#### 示例工作流程

-   "用上个月的"机器学习"标记我的研究笔记"
-   "更新我项目说明中的状况 以"完成"并添加今天的日期"
-   "发现上面提到"API设计" 并起草一个指南"
-   "审查我未加标记的笔记,并根据内容建议标签"

## 解决问题

### 共同问题

#### 未找到命令 : npx

-   **解决方案 :** 安装节点.js运行时间 [节点js.org](https://nodejs.org/)
-   **备选案文:** 使用全局安装 : `npm install -g @bitbonsai/mcpvault`

#### 当路径看起来正确时“ 找不到文件 ”

-   **原因 :** 服务器使用错误的金库根
-   **解决方案 :** 要么从您的金库目录中运行命令, 要么明确通过金库路径

#### "拒绝"错误

-   **原因 :** 文件系统权限不足
-   **解决方案 :** 确保您的用户可读/ 可写入金库目录

#### "Path traversal不允许"

-   **原因 :** 试图访问金库外的文件
-   **解决方案 :** 所有文件路径都必须与金库根相对

#### AI 客户端无法识别服务器

1.  检查您的 OS 配置文件路径正确
2.  确保 JSON 语法有效(使用 JSON 验证符)
3.  配置更改后重新启动您的AI客户端
4.  检查您的 AI 客户端的日志中的错误信息
5.  校验您的 AI 客户端支持 MCP( 模式上下文协议)

#### ". . . .

-   **预期:** 路径过滤器自动排除 `.obsidian/**` 模式
-   **如果还见到他们:** 过滤器是安全的

### 调试模式

以错误记录运行 :

```bash
npx @bitbonsai/mcpvault /path/to/vault 2>debug.log
```

### 获取帮助

-   [打开一个问题](https://github.com/bitbonsai/mcpvault/issues) 关于 GitHub 的
-   包含您的 OS, Node.js 版本和错误消息
-   提供金库目录结构( 不含敏感内容)

## 测试

运行测试套件 :

```bash
npm test
```

## API 方法

### `read_note`

从保险库里读一张纸条 上面写着解析过的前题.

**请:**

```json
{
  "name": "read_note",
  "arguments": {
    "path": "project-ideas.md",
    "prettyPrint": false
  }
}
```

**压缩响应 :**

```json
{
  "fm": {
    "title": "Project Ideas",
    "tags": ["projects", "brainstorming"],
    "created": "2023-01-15T10:30:00.000Z"
  },
  "content": "# Project Ideas\n\n## AI Tools\n- MCP server for Obsidian\n- Voice note transcription\n\n## Web Apps\n- Task management system"
}
```

**反应( 使用 pretty Print: true ):**

```json
{
  "fm": {
    "title": "Project Ideas",
    "tags": ["projects", "brainstorming"],
    "created": "2023-01-15T10:30:00.000Z"
  },
  "content": "# Project Ideas\n\n## AI Tools\n- MCP server for Obsidian\n- Voice note transcription\n\n## Web Apps\n- Task management system"
}
```

### `write_note`

使用可选的前题向金库写出注释并写入模式 .

**写入模式 :**

-   `overwrite` (默认):替换全部文件内容
-   `append`: 在现有文件末尾添加内容
-   `prepend`: 在现有文件开头添加内容

**请求( 覆盖) :**

```json
{
  "name": "write_note",
  "arguments": {
    "path": "meeting-notes.md",
    "content": "# Team Meeting\n\n## Agenda\n- Project updates\n- Next milestones",
    "frontmatter": {
      "title": "Team Meeting Notes",
      "date": "2023-12-01",
      "tags": ["meetings", "team"]
    },
    "mode": "overwrite"
  }
}
```

**请求(附录):**

```json
{
  "name": "write_note",
  "arguments": {
    "path": "daily-log.md",
    "content": "\n\n## 3:00 PM Update\n- Completed project review\n- Started new feature",
    "mode": "append"
  }
}
```

**回应:**

```json
{
  "message": "Successfully wrote note: meeting-notes.md (mode: overwrite)"
}
```

### `patch_note`

替换现有音符中的精确字符串,而不重写完整文件 .

**请:**

```json
{
  "name": "patch_note",
  "arguments": {
    "path": "meeting-notes.md",
    "oldString": "- Next milestones",
    "newString": "- Next milestones (owner: Alex)",
    "replaceAll": false
  }
}
```

**答复(成功):**

```json
{
  "success": true,
  "path": "meeting-notes.md",
  "message": "Successfully replaced 1 occurrence",
  "matchCount": 1
}
```

**响应( 以 Alll=false 替换为多匹配) :**

```json
{
  "success": false,
  "path": "meeting-notes.md",
  "message": "Found 3 occurrences of the string. Use replaceAll=true to replace all occurrences, or provide a more specific string to match exactly one occurrence.",
  "matchCount": 3
}
```

### `list_directory`

在金库中列出文件和目录 .

注:这包括非注解文件名(例如: `pdf`, (中文(简体) ), `png`, (中文(简体) ), `jpg`),所以AI助手可以看到金库结构,但音符工具如 `read_note` 财务报告和审定财务报表 `write_note` 仍然仅在便笺文件中操作( e)`.md`, (中文(简体) ), `.markdown`, (中文(简体) ), `.txt`, (中文(简体) ), `.base`, (中文(简体) ), `.canvas`) (中文(简体) ).

**请:**

```json
{
  "name": "list_directory",
  "arguments": {
    "path": "Projects",
    "prettyPrint": false
  }
}
```

**压缩响应 :**

```json
{
  "dirs": ["AI-Tools", "Web-Development"],
  "files": ["project-template.md", "roadmap.md"]
}
```

### `delete_note`

从金库中删除一纸条(安全需要确认).

**请:**

```json
{
  "name": "delete_note",
  "arguments": {
    "path": "old-draft.md",
    "confirmPath": "old-draft.md",
    "trashMode": "local"
  }
}
```

**答复(成功):**

```json
{
  "success": true,
  "path": "old-draft.md",
  "message": "Successfully moved note to vault trash: old-draft.md"
}
```

**回收站模式 :**

-   `none` (默认):永久删除
-   `local`: 移动到 `.trash` 保存文件夹结构
-   `system`: 移动到 OS 垃圾/回收桶

**答复(确认失败):**

```json
{
  "success": false,
  "path": "old-draft.md",
  "message": "Deletion cancelled: confirmation path does not match. For safety, both 'path' and 'confirmPath' must be identical."
}
```

**确认:** `confirmPath` 必须完全匹配 `path` 在删除之前.

### `get_frontmatter`

只从注释中取出前题而不读出全部内容 .

**请:**

```json
{
  "name": "get_frontmatter",
  "arguments": {
    "path": "project-ideas.md",
    "prettyPrint": false
  }
}
```

**压缩响应, 直接返回前题 :**

```json
{
  "title": "Project Ideas",
  "tags": ["projects", "brainstorming"],
  "created": "2023-01-15T10:30:00.000Z"
}
```

### `manage_tags`

在附注中添加、删除或列表标记。 标记在前题被管理,并且检测到内置标记.

**请求( 列表标记) :**

```json
{
  "name": "manage_tags",
  "arguments": {
    "path": "research-notes.md",
    "operation": "list"
  }
}
```

**请求( 添加标记 ) :**

```json
{
  "name": "manage_tags",
  "arguments": {
    "path": "research-notes.md",
    "operation": "add",
    "tags": ["machine-learning", "ai", "important"]
  }
}
```

**请求( 删除标记) :**

```json
{
  "name": "manage_tags",
  "arguments": {
    "path": "research-notes.md",
    "operation": "remove",
    "tags": ["draft", "temporary"]
  }
}
```

**回应:**

```json
{
  "path": "research-notes.md",
  "operation": "add",
  "tags": ["research", "ai", "machine-learning", "important"],
  "success": true,
  "message": "Successfully added tags"
}
```

### `search_notes`

以多字匹配和BM25相关性重排的内容或前题搜索金库中的音符.

**请:**

```json
{
  "name": "search_notes",
  "arguments": {
    "query": "machine learning",
    "limit": 5,
    "searchContent": true,
    "searchFrontmatter": false,
    "caseSensitive": false,
    "prettyPrint": false
  }
}
```

**压缩响应 :**

```json
[
  {
    "p": "ai-research.md",
    "t": "AI Research Notes",
    "ex": "...machine learning...",
    "mc": 2,
    "ln": 15,
    "uri": "obsidian://open?vault=MyVault&file=ai-research.md"
  }
]
```

**字段名称 :**

-   `p` = 路径
-   `t` = 标题
-   `ex` = 节选(21个字符上下文)
-   `mc` = 匹配数
-   `ln` =行号
-   `uri` = 快速打开的深层链接

### `move_note`

在金库中移动或重命名一个便条( Name`.md`, (中文(简体) ), `.markdown`, (中文(简体) ), `.txt`, (中文(简体) ), `.base`, (中文(简体) ), `.canvas`) (中文(简体) ).

**请:**

```json
{
  "name": "move_note",
  "arguments": {
    "oldPath": "drafts/article.md",
    "newPath": "published/article.md",
    "overwrite": false
  }
}
```

**回应:**

```json
{
  "success": true,
  "oldPath": "drafts/article.md",
  "newPath": "published/article.md",
  "message": "Successfully moved note from drafts/article.md to published/article.md"
}
```

### `move_file`

用二进制安全文件操作来移动或重命名金库中的任何文件(仅文件;不是递归目录动作). 为了安全起见,这个工具需要确认源道和去向道.

**请:**

```json
{
  "name": "move_file",
  "arguments": {
    "oldPath": "Miro/attachments/Pasted image 20250812140124.png",
    "newPath": "assets/images/Pasted image 20250812140124.png",
    "confirmOldPath": "Miro/attachments/Pasted image 20250812140124.png",
    "confirmNewPath": "assets/images/Pasted image 20250812140124.png",
    "overwrite": false
  }
}
```

**回应:**

```json
{
  "success": true,
  "oldPath": "Miro/attachments/Pasted image 20250812140124.png",
  "newPath": "assets/images/Pasted image 20250812140124.png",
  "message": "Successfully moved file from Miro/attachments/Pasted image 20250812140124.png to assets/images/Pasted image 20250812140124.png"
}
```

**确认:** `confirmOldPath` 必须匹配 `oldPath`,以及 `confirmNewPath` 必须匹配 `newPath`。 。 。 .

### `read_multiple_notes`

分批读取多笔记(最多10个文件).

**请:**

```json
{
  "name": "read_multiple_notes",
  "arguments": {
    "paths": ["note1.md", "note2.md", "note3.md"],
    "includeContent": true,
    "includeFrontmatter": true,
    "prettyPrint": false
  }
}
```

**压缩响应 :**

```json
{
  "ok": [
    {
      "path": "note1.md",
      "frontmatter": { "title": "Note 1" },
      "content": "# Note 1\n\nContent here..."
    }
  ],
  "err": [{ "path": "note2.md", "error": "File not found" }]
}
```

**字段名称 :**

-   `ok` = 读取成功
-   `err` = 读取失败

### `update_frontmatter`

更新注释的前题, 不更改内容 .

**请:**

```json
{
  "name": "update_frontmatter",
  "arguments": {
    "path": "research-note.md",
    "frontmatter": {
      "status": "completed",
      "updated": "2025-09-23"
    },
    "merge": true
  }
}
```

**回应:**

```json
{
  "message": "Successfully updated frontmatter for: research-note.md"
}
```

### `get_notes_info`

在不读取完整内容的情况下获取注释的元数据 .

**请:**

```json
{
  "name": "get_notes_info",
  "arguments": {
    "paths": ["note1.md", "note2.md"],
    "prettyPrint": false
  }
}
```

**压缩响应, 直接返回数组 :**

```json
[
  {
    "path": "note1.md",
    "size": 1024,
    "modified": 1695456000000,
    "hasFrontmatter": true
  }
]
```

### `get_vault_stats`

获取高层金库统计数据而不阅读音符内容.

**请:**

```json
{
  "name": "get_vault_stats",
  "arguments": {
    "recentCount": 5,
    "prettyPrint": false
  }
}
```

**压缩响应 :**

```json
{
  "notes": 1248,
  "folders": 76,
  "size": 18349210,
  "recent": [
    {
      "path": "Daily/2026-02-27.md",
      "modified": 1772188800000,
      "size": 2814
    }
  ]
}
```

## 安全边界

MCPVault 在文件操作前应用这些检查 :

### 路径安全

-   **路径倾斜保护 :** 所有文件路径都经过验证以防止在金库外访问
-   **相对路径执行 :** 路径正常化并限制在金库目录内
-   **符号链接安全 :** 对照金库边界检查已解析的路径

### 文件过滤

-   **自动排除:** `.obsidian`, (中文(简体) ), `.git`, (中文(简体) ), `node_modules`系统文件被过滤
-   **扩展白名单 :** 仅 `.md`, (中文(简体) ), `.markdown`, (中文(简体) ), `.txt`, (中文(简体) ), `.base`,以及 `.canvas` 文件默认可访问
-   **隐藏文件保护 :** 自动排除点文件和系统目录

### 内容验证

-   **YAML 前题验证 :** 前题在写入前解析并验证
-   **函数/符号预防:** 危险 JavaScript 对象从前题被屏蔽
-   **数据类型检查 :** 只允许安全数据类型(字符串、数字、阵列、对象)

### 最佳做法

-   **最小特权 :** 服务器只访问指定的金库目录
-   **仅读模式 :** 运行 `--read-only` 用于敏感的金库; 变异工具被隐藏并拒绝
-   **建议备份 :** 在使用写入操作前总是备份您的金库
-   **网络隔离 :** 服务器使用 stdio 传输( 不接触网络)

### 没有保护的东西

-   **文件内容 :** 服务器可以读取/写入任何允许的文件内容
-   **断层结构 :** 目录结构可见于 AI 助手
-   **文件元数据 :** 可访问创建时间、 文件大小等

只允许您信任的客户端和对话进行书面访问。 使用 `--read-only` 当客户不需要修改笔记时.

## 建筑

-   `server.ts` - MCP服务器入口
-   `src/cli.ts` - 解析库道、只读模式和默认排除的 CLI 选项
-   `src/createServer.ts` - MCP工具注册、请求路由和发现默认
-   `src/frontmatter.ts` - YAML 前事处理灰色事项, 保留格式化和 CRLF 线尾; 可执行 JavaScript 前事保留为惰性注释内容
-   `src/filesystem.ts` - 有路径验证的文件操作
-   `src/pathfilter.ts` - 目录和文件过滤
-   `src/search.ts` - 有内容和前题支持的备注搜索功能
-   `src/uri.ts` - Absidian URI 代号,用于深层链接
-   `src/types.ts` - 类型脚本类型定义

## 捐款

1.  叉子存储器
2.  创建特性分支 : `git checkout -b feature-name`
3.  更改并添加测试
4.  确保所有测试合格 : `npm test`
5.  提交拉动请求

维护者:制作出版由GitHub Releases驱动. 见 [相关内容](https://npmcn.com/package/%40bitbonsai/mcpvault/RELEASING.md)。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @bitbonsai/mcpvault 是什么？

Absidian 保险库的通用AI桥 - 连接任何兼容 MCP 的助手

### 如何安装 @bitbonsai/mcpvault？

在项目目录运行 npm install @bitbonsai/mcpvault，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcpvault，可以用 npx mcpvault 直接运行。

### @bitbonsai/mcpvault 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bitbonsai/mcpvault 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bitbonsai/mcpvault 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bitbonsai/mcpvault 可以商用吗？

@bitbonsai/mcpvault 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bitbonsai/mcpvault 的下载量有多少？

根据 npm 官方下载统计，@bitbonsai/mcpvault 在 2026/10/08 – 2026/11/06 这 30 天内被下载 74,413 次，日均约 2,480 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bitbonsai/mcpvault 还在维护吗？

最新版本 0\.18\.3 发布于 2026/11/01（7 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/03/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。