内容
# 🗄️ Obsidian-Brain-MCP (Rust)
一款用 **Rust** 编写的超快速、轻量级模型上下文协议（MCP）服务器，允许AI代理（如Cursor、Claude Desktop、Claude Code和Antigravity）安全地读取、搜索、编译关系并与本地Obsidian知识库进行交互，通过标准输入/输出（stdio）通道。
## ⚡ 为什么选择Rust？
* **零延迟：** 几毫秒内启动，直接运行原生代码。
* **最小RAM占用：** 使用少于15MB的RAM（Node.js服务器通常需要超过80MB）。
* **零依赖运行：** 编译为单个原生二进制文件。无需在目标系统上设置Node.js、Python或npm。
## 🚀 主要功能
* 🔒 **词汇路径归一化：** 内置保护机制，防止目录遍历攻击（LFI），确保AI代理永远不会逃离知识库边界。
* 🏷️ **智能标签索引：** 通过标签搜索知识库笔记（支持YAML frontmatter元数据和内联 `#tag/sub-tag` 语法）。
* 🎨 **Obsidian Canvas支持：** 允许AI直接在Obsidian中读取和“绘制”流程图、卡片和连接线，使用标准 `.canvas` 规范。
* 📅 **每日笔记路由：** 自动将条目或更新记录到今天的本地笔记（例如 `YYYY-MM-DD.md`），自动映射本地时间。
* 🕸️ **反向链接和图表编译：** 创建完整的网络图，映射节点连接和链接边。
## ⚙️ 快速开始
### 1. 构建二进制文件
克隆仓库并编译优化的发布二进制文件：
```bash
cargo build --release
```
编译后的二进制文件将位于：
* **Windows：** `target/release/obsidian-brain-mcp.exe`
* **macOS / Linux：** `target/release/obsidian-brain-mcp`
## 🔌 连接到LLM客户端
### 1. Cursor IDE（设置指南）
1. 打开Cursor并转到 **设置** -> **功能** -> **MCP**。
2. 点击 **+ 添加新的MCP服务器**。
3. 配置设置：
* **名称：** `obsidian-brain`
* **类型：** `stdio`
* **命令：**
```bash
C:/path/to/obsidian-brain-mcp/target/release/obsidian-brain-mcp.exe --vault "C:/path/to/your/obsidian/vault"
```
*(确保将 `C:/path/to/obsidian-brain-mcp` 替换为克隆此仓库的实际文件夹路径)。*
4. 点击 **保存**。服务器状态指示器将变为绿色！
### 2. Claude Desktop（设置指南）
将此配置片段添加到您的Claude Desktop配置文件中：
* **Windows：** `%APPDATA%\Claude\claude_desktop_config.json`
* **macOS：** `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"obsidian-brain": {
"command": "C:/path/to/obsidian-brain-mcp/target/release/obsidian-brain-mcp.exe",
"args": [
"--vault",
"C:/path/to/your/obsidian/vault"
]
}
}
}
```
## 🛠️ 公开MCP工具参考
| 工具名称 | 参数 | 描述 |
| :--- | :--- | :--- |
| `list_notes` | 无 | 递归列出知识库中的所有Markdown笔记（显示路径、标题和大小）。 |
| `read_note` | `path`（字符串） | 读取笔记路径的原始文本内容。 |
| `write_note` | `path`（字符串），`content`（字符串） | 创建新笔记或完全覆盖现有笔记。 |
| `append_to_note` | `path`（字符串），`content`（字符串） | 将文本内容追加到笔记（如果笔记不存在则创建）。 |
| `append_to_daily_note`| `content`（字符串） | 解析本地日期并将内容追加到今天的每日笔记（例如 `YYYY-MM-DD.md`）。 |
| `search_notes` | `query`（字符串） | 关键字搜索所有笔记（不区分大小写的全文查找）。 |
| `search_by_tag` | `tag`（字符串） | 过滤并返回包含指定标签的笔记路径（YAML或内联 `#tag`）。 |
| `get_backlinks` | `note_name`（字符串） | 查找所有引用目标笔记的其他笔记。 |
| `get_graph` | 无 | 编译双括号关系的节点和边。 |
| `create_canvas` | `path`（字符串），`nodes`（数组），`edges`（数组） | 编写/创建Obsidian Canvas JSON白板。 |
| `read_canvas` | `path`（字符串） | 读取 `.canvas` 文件并格式化为人类可读的轮廓。 |
## 🧩 高级用法示例
### 1. 标签过滤（`search_by_tag`）
您可以在frontmatter或笔记中间标记文件：
```markdown
---
tags: [ai, agent]
---
# 设置
这是一个 #obsidian/mcp 服务器节点。
```
调用 `search_by_tag(tag: "ai")` 或 `search_by_tag(tag: "#obsidian/mcp")` 会立即返回此笔记的文件路径。
### 2. Canvas操作（`create_canvas`）
使用标准参数以编程方式创建图表。
* **`nodes` 格式：** `[{ "id": "node-id", "x": 0, "y": 0, "width": 200, "height": 80, "type": "text"|"file", "text": "optional card content", "file": "optional_note_link.md" }]`
* **`edges` 格式：** `[{ "id": "edge-id", "fromNode": "source-id", "fromSide": "right", "toNode": "target-id", "toSide": "left" }]`
## 🧪 开发与测试
运行内置的单元测试以验证解析器和路径安全模式：
```bash
cargo test
```
运行集成压力测试以检查目录遍历防御、模糊测试和线程并发限制：
```bash
python test_mcp.py
```
