内容
# Obsidian 语义 MCP
[](https://github.com/artificemachine/obsidian-semantic-mcp/actions/workflows/tests.yml)
[](LICENSE)
[](pyproject.toml)
[](https://hub.docker.com/r/newblacc/obsidian-semantic-mcp)
## 概述
Claude Desktop 的持久化内存层 - 使用本地嵌入和 PostgreSQL + pgvector 在您的整个 Obsidian 保险箱中进行语义搜索。
## 问题
AI 助手在每次会话后都会忘记所有内容。您需要重复上下文信息，失去连续性，每次都从头开始。您的笔记、项目和偏好都存储在 Obsidian 中，但无法自动进入 AI 对话中。
## 解决方案
**Obsidian 语义 MCP** 将您的 Obsidian 保险箱变成一个可查询的大脑，适用于 Claude。它：
- 将每个笔记索引为一个向量嵌入（通过 Ollama + `nomic-embed-text`）
- 将嵌入存储在 PostgreSQL 中，使用 pgvector 进行快速语义搜索
- 监视您的保险箱是否有变化，并自动重新索引
- 提供整个保险箱的 CRUD（创建、读取、搜索、列出）- 即使 Obsidian 已关闭也适用
- 通过 MCP 将所有内容公开给 Claude，以便其可以实时检索和管理保险箱内容
无需云服务，无需 API 密钥。所有内容都在本地运行。
## 快速开始
使用您所在平台的引导安装程序。如果您已经克隆了仓库，可以跳过引导并直接运行 `uv run osm init`。
### 前 60 秒（新用户）
如果您在全新环境中（尚未安装 `osm` 启动器），请从仓库根目录运行以下命令。
**选择适合您操作系统的模式** - 推荐路径是全 Docker（容器中运行所有内容，无需安装 Docker 以外的任何内容）：
| 操作系统 | 推荐 `--mode` |
|----|----------------------|
| macOS | `--mode 3` |
| Linux / Windows | `--mode 2` |
```bash
# 1) 安全预览设置操作 - 不会做出任何更改（使用您选择的模式）
uv run osm init --dry-run --mode 3 --vault "/path/to/your/vault" --pg-password "obsidian" --persistent --data-dir "/path/to/data"
# 2) 实际运行设置
uv run osm init --mode 3 --vault "/path/to/your/vault" --pg-password "obsidian" --persistent --data-dir "/path/to/data"
# 3) 打开监控仪表盘
uv run osm dashboard
```
> 上述命令使用 `--mode 3`（macOS）。在 Linux/Windows 上使用 `--mode 2`。
> 如果您已经在本地运行 Ollama，请使用 `--mode 4`（Docker + 主机 Ollama）跳过重新下载 Ollama 镜像和模型。
> `--mode 1` 是 **本地**（非 Docker）macOS 安装 - 仅当您特别希望 Postgres 和服务器在容器外运行时选择此选项。
> 对于临时/CI 设置，请使用 `--no-persistent` 代替。
> **平台支持：** Linux 是 CI 测试路径 - 完整的测试套件（包括 PostgreSQL 集成测试）在 `ubuntu-latest` 上运行。macOS 通过 `osm init --mode 3`（Docker Desktop 在推荐路径上）支持，但尚未涵盖 CI。Windows 通过 WSL2 Docker 后端和 `install.ps1` / `osm.ps1` 启动器支持，但 **尚未涵盖 CI**；将其视为社区测试，直到 Windows 运行器上线。
**开始前：**
- **`uv`** 必须已安装 - `curl -LsSf https://astral.sh/uv/install.sh | sh`（macOS/Linux）或 `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`（Windows）
- **Docker Desktop** - 向导将提供自动安装（如果缺少）`brew`（macOS）、`winget`（Windows）或 `get.docker.com`（Linux）。在 Windows 上，请启用 WSL2 后端。
- 知道您的保险箱路径 - 在 Obsidian 中：设置 → 关于 → 保险箱位置
### 1. 引导并运行设置向导
**macOS / Linux：**
```bash
curl -fsSL https://raw.githubusercontent.com/artificemachine/obsidian-semantic-mcp/main/install.sh | bash
```
> 如果 `~/.local/share/obsidian-semantic-mcp` 已经存在，安装程序会更新该目录，然后继续。如果该安装目录有未提交的本地更改，更新步骤可能会中止并出现 Git 合并错误。在这种情况下，请提交/隐藏这些更改，或者直接使用当前的 checkout 运行 `uv run osm init`。
**Windows PowerShell：**
```powershell
powershell -c "irm https://raw.githubusercontent.com/artificemachine/obsidian-semantic-mcp/main/install.ps1 | iex"
```
> **提示：** 引导安装程序会为您启动 `osm init`。安装完成后，您可以从现有 checkout 运行 `osm init --dry-run` 以预览所有操作而不进行任何更改。
>
> 如果您已经克隆了仓库，`scripts/osm`（macOS/Linux）和 `scripts/osm.ps1`（Windows PowerShell）与引导安装程序的作用相同。
> 如果您更喜欢手动 checkout，请克隆仓库并从项目根目录运行 `uv run osm init`。
>
> **一个服务器，所有项目：** `obsidian-semantic` 在全局范围内注册 - 从任何其他项目运行 `osm init` 是安全且幂等的。如果已经配置，它会跳过注册并通知您。
>
> **OpenCode/GitHub Copilot 注意：** 在此仓库中，`osm` 指的是 **Obsidian Semantic MCP CLI**，而不是 OpenStreetMap。在新的聊天会话中，请显式运行命令（例如 `osm dashboard`）以避免首字母缩写歧义。
>
> **如果找不到 `osm`：** 使用 `uv run osm <command>` 从仓库根目录（例如 `uv run osm init --dry-run`）。
>
> **会话启动器（复制/粘贴）：**
> ```text
> 在此仓库中，"osm" 指的是 obsidian-semantic-mcp CLI（不是 OpenStreetMap）。
> 请直接执行 shell 命令。
> 如果找不到 `osm`，请从仓库根目录使用 `uv run osm ...`。
> 示例：osm init, osm dashboard。
> ```
引导安装程序会克隆到本地数据目录，创建 `osm` 的 PATH shim，并启动向导。
向导会检测您的操作系统，并询问您要哪种安装模式：
**macOS：**
```
1) 原生 Homebrew + 本地 Postgres + 本地 Ollama
2) Docker + 主机 Ollama Docker 中的 Postgres，Ollama 已在此 Mac 上运行
3) 全 Docker 所有内容都在容器中（推荐）
4) Docker + 远程 Ollama Docker 中的 Postgres，Ollama 在另一台机器上运行
```
**Linux：**
```
1) Docker + 主机 Ollama Docker 中的 Postgres，Ollama 在此机器上运行
2) 全 Docker 所有内容都在容器中（推荐）
3) Docker + 远程 Ollama Docker 中的 Postgres，Ollama 在另一台机器上运行
```
**Windows（需要 Docker Desktop 和 WSL2 后端）：**
```
1) Docker + 主机 Ollama Docker 中的 Postgres，Ollama 已在此 PC 上运行
2) 全 Docker 所有内容都在容器中（推荐）
3) Docker + 远程 Ollama Docker 中的 Postgres，Ollama 在另一台机器上运行
```
> **选择哪种模式？** 除非您已经在本地运行 Ollama，否则请选择 **全 Docker**（macOS 上的模式 3，Linux/Windows 上的模式 2），以避免重新下载 Ollama 镜像和模型。
然后：
- 设置本地安装目录和 PATH shim
- 安装前提条件或验证它们已经存在（如果缺少，Docker 将被安装并自动启动）
- 如果需要，拉取 `nomic-embed-text`
- 编写一个 `.env` 文件（gitignored），其中包含您的保险箱路径和凭证
- 自动更新 **Claude Desktop**、**Claude Code CLI**、**OpenCode** 和 **pi**（如果已安装）的 MCP 客户端配置
- 在生成的 MCP 条目中使用仓库启动器脚本，因此启动不依赖原始 Docker 命令或容器特定配置
### 2. 重启您的 MCP 客户端
重启 Claude Desktop / OpenCode 以获取新的服务器。对于 Claude Code CLI，条目已实时注册；请使用 `claude mcp list` 验证。对于 pi，请在活动会话中运行 `/reload` 或重启 pi。
> **pi 用户：** `osm init` 还会修补 `~/.pi/agent/extensions/mcp-bridge.ts`（如果存在）。obsidian-semantic 需要 `heartbeat: true` 和启动时心跳输入桥接器，详见 [`docs/pi_mcp_bridge_heartbeat.md`](docs/pi_mcp_bridge_heartbeat.md)。
> **手动配置（仅当 `osm init` 无法检测到您的客户端时）**
>
> 将以下内容添加到 `~/.opencode.json`、`claude_desktop_config.json` 或您的 MCP 客户端使用的任何 JSON 配置文件中：
> ```json
> {
> "mcpServers": {
> "obsidian-semantic": {
> "command": "/absolute/path/to/obsidian-semantic-mcp/scripts/obsidian-semantic-mcp",
> "args": [],
> "env": {}
> }
> }
> }
> ```
> 将 `/absolute/path/to/obsidian-semantic-mcp` 替换为您的本地克隆路径。启动器优先使用正在运行的 Docker 堆栈，并在使用 Docker 时回退到本地 `.venv`。
### 3. 首次索引
服务器会在首次运行时索引您的保险箱，然后自动监视更改。
> **首次索引大约需要 1–2 秒/笔记** - 预计 500 笔保险箱需要 5–15 分钟。在 http://localhost:8484 上监视进度。Claude 在索引完成之前不会返回任何结果。
> 更喜欢在没有 Docker 的情况下运行？请参阅 [本地安装（macOS）](#native-install-macos)。
> 想要跳过向导？请参阅 [手动启动（无需向导）](#manual-start-without-wizard)。
---
### 本地安装（macOS）
不喜欢运行 Docker？`osm init --mode 1` 通过 Homebrew 安装 PostgreSQL + pgvector 和 Ollama，并在进程中运行 MCP 服务器 - 无容器。此选项适用于您已经避免使用 Docker，或者希望服务器直接共享您的 Mac 原生 Ollama 安装。
```bash
uv run osm init --mode 1 --vault "/path/to/your/vault"
```
此模式使用 `OBSIDIAN_VAULT`/`DATABASE_URL` 直接在条目上注册（Docker 模式相反，加载 `.env` 启动器通过运行容器的项目根目录找到）- 重启您的 MCP 客户端后，与其他模式相同。
### 手动启动（无需向导）
```bash
OBSIDIAN_VAULT="/path/to/your/vault" POSTGRES_PASSWORD=obsidian docker compose up -d
```
> Docker Compose 还会读取仓库根目录中的 `.env` 文件（gitignored）。
首次运行会拉取所有镜像和 `nomic-embed-text` 模型。这会启动：
| 服务 | 端口 | 描述 |
|---------|------|-------------|
| PostgreSQL + pgvector | 5433 | 矢量存储（避免与主机 pg 冲突） |
| Ollama | 11435 | 本地嵌入（自动拉取模型） |
| MCP 服务器 | stdio | 客户端通过 `scripts/obsidian-semantic-mcp` 连接，该脚本优先使用 Docker 并在 Docker 无可用时回退到本地 `.venv` |
| 仪表盘 | 8484 | http://localhost:8484 |
### 有用的命令
```bash
# 查看服务器日志
docker compose logs -f mcp-server
# 代码更改后重建
docker compose up -d --build mcp-server dashboard
# 停止所有内容
docker compose down
# 停止并清除所有数据（从头开始重新索引）
# ⚠️ 警告：-v 删除所有索引嵌入。重新索引将从头开始。
docker compose down -v
```
### GPU 支持（可选）
对于 Linux 上的 NVIDIA GPU，请在 `docker-compose.yml` 中为 `ollama` 服务添加以下内容：
```yaml
deploy:
resources:
reservations:
devices:
- capabilities: [gpu]
```
### 故障排除
安装时遇到的前 3 个问题：
- **无搜索结果 / Claude 说服务器未连接** - 首次运行索引需要 5–15 分钟，适用于 500 笔保险箱；在 http://localhost:8484 或 `docker compose logs -f mcp-server` 上监视进度。
- **Postgres 连接失败** - 检查容器是否健康：`docker compose ps`，然后 `docker compose exec postgres pg_isready -U obsidian`。
- **Ollama 无法访问** - 确认它正在运行：`curl http://localhost:11434/api/tags`（或远程 Ollama 模式的 SSH 隧道的本地端口）。
完整的事件指南，包括恢复步骤：[`docs/RUNBOOK.md`](docs/RUNBOOK.md)。
## 与 Claude 一起使用
MCP 服务器连接后，Claude 可以直接访问您的保险箱 - 无需特殊语法。只需自然地与它对话。
### 示例提示
```
"在我的笔记中搜索有关项目 X 的任何内容"
" 我上个月写了什么关于酮症的内容？"
" 查找我的关于 Zettelkasten 方法的笔记"
" 读取我的 Daily/2026-03-14.md 笔记"
" 将此会议摘要追加到我的收件箱笔记"
" 在 Projects/obsidian-mcp.md 处创建一个包含此内容的笔记"
" 列出 Fleeting 文件夹中的所有文件"
" 显示最近修改的内容"
" 重新索引我的保险箱"
```
Claude 将根据您的请求自动选择正确的 MCP 工具（`search_vault`、`get_file`、`write_file` 等）。
### osm - 设置和管理 CLI
使用 `osm` 来设置、管理和关闭堆栈。向导安装所有前提条件，配置 Docker，并自动更新 Claude Desktop。
`osm` 在此仓库中指 Obsidian Semantic MCP CLI（不是 OpenStreetMap）。
| 命令 | 描述 |
|---------|-------------|
| `osm init` | 交互式设置向导 |
| `osm init --mode <1-4> --vault <path>` | 非交互式设置（代理/脚本友好） |
| `osm init --dry-run` | 预览所有操作而不进行任何更改 |
| `osm status` | 检查服务健康状况（Docker、Ollama 可达性/推理，Claude Desktop） |
| `osm vaults` | 列出配置的 Obsidian 保险箱（s） |
| `osm dashboard` | 在浏览器中打开监控仪表盘 |
| `osm rebuild` | 代码更改后重建 Docker 镜像 |
| `osm tunnel` | 重新连接 SSH 隧道（远程 Ollama 模式） |
| `osm remove` | 停止服务并清除所有卷和配置 |
| `osm remove --yes` | 非交互式拆卸（代理/脚本友好） |
| `osm help` | 完整的标志引用 |
`osm init` 标志： `--mode`、`--vault`、`--pg-password`、`--persistent` / `--no-persistent`、`--data-dir`、`--ssh-host`、`--ssh-user`、`--ssh-port`、`--ssh-key`、`vault-remote`
`osm status` 探测 Ollama 可达性（`/api/tags`）和嵌入（`/api/embedments`），因此它可以`` ），因此它可以捕获守护进程启动但模型执行损坏的情况。
> **Windows 启动器：** `osm init` 安装 `osm.cmd` 到 `%USERPROFILE%\.local\bin\`。Windows 自动解析 `.cmd`，因此您可以从任何终端将其称为 `osm`。如果找不到 `osm`，请将 `%USERPROFILE%\.local\bin` 添加到您的 `Path` 环境变量中。
### 与 Claude Code、Codex 和 OpenCode 一起使用
当您直接在终端中键入 `osm init` 或 `osm dashboard` 时，这些命令将正常运行。
在基于聊天的编码代理中，裸 `osm ...` 消息可能会被解释为文本（或 OpenStreetMap）而不是 shell 命令。要强制执行，请明确说明：
- `Run osm init`
- `Run osm dashboard`
如果启动器尚未安装（或不在 PATH 上），请使用：
- `Run uv run osm init --dry-run --mode 1 --vault <vault-path> --pg-password <password>`
- `Run uv run osm dashboard`
期望新用户：
- 首次安装：`osm init` 设置服务并在该 OS 用户的全局 MCP 配置中注册 `obsidian-semantic`。
- 后续会话：重新运行 `osm init` 是安全且幂等的。
- `osm dashboard` 打开 `http://localhost:8484`；如果堆栈尚未运行，它会警告并仍打开 URL。
**会话启动器（复制/粘贴）：**
```text
在这个仓库中，"osm" 指的是 obsidian-semantic-mcp CLI（不是 OpenStreetMap）。
请直接执行 shell 命令。
如果找不到 `osm`，请从仓库根目录使用 `uv run osm ...`。
示例：osm init, osm dashboard。
```
### 示例输出
当 Claude 搜索您的保险箱时，结果按相似度得分和内容预览排名：
```
## 搜索： “我写了什么关于酮症的内容”
1. health/ketosis-diet.md（相似度：0.87）
酮症是一种代谢状态，身体以脂肪为燃料燃烧...
2. Daily/2026-03-14.md（相似度：0.72）
今天开始酮饮食。周一准备了膳食...
3. research/low-carb-studies.md（相似度：0.65）
最近关于低碳水化合物饮食的研究表明...
```
对于保险箱的 CRUD 操作，`get_file` 返回完整的笔记内容；`recent_changes` 列出最近修改的文件及其时间戳。
## 架构
```
Claude Desktop
↓ MCP 协议（stdio）
src/server.py（统一 MCP 服务器）
├── 语义搜索（pgvector 余弦相似度）
├── 保险箱 CRUD（直接文件系统访问）
└── 实时文件监视器（监视器）
↓
PostgreSQL + pgvector（矢量存储 + IVFFlat 索引）
↓
Ollama / nomic-embed-text（本地 768 维嵌入）
↓
您的 Obsidian 保险箱（例如 $HOME/Documents/MyVault）
```
## 项目结构
```
obsidian-semantic-mcp/
├── install.sh # macOS/Linux 引导安装程序
├── install.ps1 # Windows PowerShell 引导安装程序
├── scripts/
│ ├── osm # CLI 包装器（macOS/Linux）- `uv run osm init` 或 `scripts/osm init`
│ └── osm.ps1 # CLI 包装器（Windows）- `.\scripts\osm.ps1 init`
├── src/
│ ├── server.py # MCP 服务器 - 语义搜索 + 保险箱 CRUD（11 种工具）
│ └── dashboard.py # 监控仪表盘（http://localhost:8484）
├── tests/
│ ├── test_unit.py # 单元测试（无需真实数据库/奥拉玛）
│ ├── test_osm_init.py # osm CLI 向导的单元测试
│ ├── test_dashboard_smoke.py # 仪表盘静态分析 + 实时 HTTP 冒烟测试
│ ├── test_setup.py # 先决条件检查器（依赖项，数据库，奥拉玛）- 直接运行
│ └── test_e2e.py # 端到端 MCP 协议测试 - 直接运行
├── osm_init.py # 交互式设置向导（由 scripts/osm 使用）
├── Dockerfile # Python 3.13 + uv
├── docker-compose.yml # 完整堆栈：postgres, ollama, server, dashboard
├── pyproject.toml # 项目元数据 + 依赖项（osm 脚本入口）
├── uv.lock # 锁定文件
└── LICENSE # Apache 2.0
```
## 前置条件
- 文件系统中有一个Obsidian vault
- **macOS原生：** Homebrew（自动安装其他所需组件）
- **Docker模式：** Docker Desktop（macOS/Linux/Windows）—— 向导提供通过`brew`（macOS）、`winget`（Windows）或`get.docker.com`（Linux）安装它，并在启动守护进程
- **Windows：** 启用WSL2后端，通过`powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`安装`uv`
## MCP工具
### 语义搜索
| 工具 | 描述 |
|------|-------------|
| `search_vault` | 在整个vault中进行语义搜索。返回具有相似度得分的排名摘要。支持`graph_expand: true`以跟随顶级结果的wikilinks并显示连接的笔记。 |
| `simple_search` | 在vault文件中进行精确文本/关键词搜索。 |
| `get_note_connections` | 返回通过wikilinks与给定笔记连接的所有笔记——包括出站链接和入站反向链接。对于探索知识图谱和查找相关笔记非常有用。 |
### Vault管理
| 工具 | 描述 |
|------|-------------|
| `list_files` | 列出vault目录中的文件和目录。 |
| `get_file` | 读取单个文件的完整内容。 |
| `get_files_batch` | 一次读取多个文件。 |
| `append_content` | 将内容追加到文件中（如果文件不存在则创建）。 |
| `write_file` | **覆盖**目标文件——现有内容将被替换，无法撤销。如果要添加到现有文件中，请使用`append_content`。 |
| `recent_changes` | 获取最近修改的文件。 |
### 索引管理
| 工具 | 描述 |
|------|-------------|
| `list_indexed_notes` | 列出所有已索引的笔记及其最后索引时间戳。 |
| `reindex_vault` | 强制对所有笔记进行完整重新索引。在后台运行。 |
## 多Vault支持
要索引多个vault，请将`OBSIDIAN_VAULTS`设置为以逗号分隔的绝对路径列表：
```bash
OBSIDIAN_VAULTS="/path/to/vault1,/path/to/vault2" docker compose up -d
```
或在docker-compose.yml中（取消注释多vault行）：
```yaml
environment:
OBSIDIAN_VAULTS: /vault1,/vault2 # 多vault
volumes:
- /path/to/vault1:/vault1
- /path/to/vault2:/vault2
```
使用多个vault时，`search_vault` MCP工具获得一个`vault`参数，用于按vault名称筛选结果。仪表板还会显示一个vault选择器。每个vault都独立监视和索引。
## 工作原理
1. **索引** — 启动时，服务器遍历您的vault，读取每个`.md`文件，通过Ollama生成一个768维的嵌入，并将其上载到PostgreSQL的pgvector中。未更改的文件（相同的SHA-256哈希）在后续运行中被跳过。**首次索引大约每条笔记需要1-2秒**，使用本地Ollama实例——预计一个包含500条笔记的vault需要5-15分钟。在http://localhost:8484或通过`docker compose logs -f mcp-server`查看进度。
2. **监视** — 文件监视器（`watchdog`）监视vault的创建、更新、删除和移动——自动重新嵌入更改的文件。
3. **搜索** — 当Claude调用`search_vault`时，查询被嵌入并与存储的向量进行匹配，使用余弦相似度（IVFFlat索引）。顶级结果返回带有相似度得分和内容预览。
4. **CRUD** — 所有文件操作都使用直接文件系统访问，因此服务器无论Obsidian是否打开都可以使用。阻止vault外的路径遍历。
## 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `OBSIDIAN_VAULT` | Obsidian vault的绝对路径。挂载为**读写**，以便MCP写入/追加工具可以创建和更新笔记。如果只需要搜索，请使用`:ro`挂载。 | *必填* |
| `OBSIDIAN_VAULTS` | 多vault模式下的vault路径逗号分隔列表。设置时覆盖`OBSIDIAN_VAULT`。 | — |
| `OBSIDIAN_IGNORE_PATHS` | 索引和监视期间要跳过的vault相对路径段的逗号分隔列表。默认为`archive`；设置为空字符串以索引存档笔记。 | `archive` |
| `POSTGRES_PASSWORD` | PostgreSQL密码（Docker） | *Docker必填* |
| `DATABASE_URL` | 完整的连接字符串（覆盖POSTGRES_*变量） | 从POSTGRES_*变量构建 |
| `POSTGRES_HOST` | PostgreSQL主机 | `localhost` |
| `POSTGRES_PORT` | PostgreSQL端口 | `5432` |
| `POSTGRES_DB` | 数据库名称 | `obsidian_brain` |
| `POSTGRES_USER` | 数据库用户 | `obsidian` |
| `OLLAMA_URL` | Ollama API端点 | `http://localhost:11434` |
| `EMBEDDING_MODEL` | Ollama嵌入模型 | `nomic-embed-text` |
| `EMBED_WORKERS` | 批量索引的并行线程 | `4` |
| `RERANK_MODEL` | 可选的Ollama模型，用于交叉编码器重新排序（例如`llama3.2`）。为空时禁用。 | — |
| `RERANK_CANDIDATES` | 重新排序前获取的候选池大小 | `20` |
| `DASHBOARD_BIND` | 监视仪表板绑定的接口。默认环回；仅在本地安装中设置为`0.0.0.0`，以便从另一个主机访问。 | `127.0.0.1` |
| `DASHBOARD_TOKEN` | 仪表板变异端点的Bearer令牌。如果未设置，则在`~/.config/obsidian-semantic-mcp/dashboard_token`（模式`0600`）中生成和存储。 | *自动生成* |
| `OSM_SKIP_PI` | 设置为`1`以跳过在`osm init`期间配置可选的`pi` MCP客户端，即使安装了`pi`二进制文件。对于大多数用户（没有`pi`），这对于干净的设置非常有用。 | — |
## 监控仪表板
内置仪表板可在http://localhost:8484访问（使用Docker自动启动）。它显示：
- 服务健康状况（PostgreSQL、Ollama、嵌入模型）
- 已索引笔记数、vault覆盖率、数据库大小
- 最近索引的文件（可折叠 — 点击标题隐藏/显示）
- **重新索引** — 增量重新索引（跳过未更改的笔记，速度快）
- **清除并重建** — 清除所有嵌入并从头开始重新索引
- 如果Ollama关闭，则会出现“启动Ollama”按钮
在没有Docker的情况下运行仪表板：
```bash
OBSIDIAN_VAULT="/path/to/your/vault" uv run python3 src/dashboard.py
```
## 测试
### 单元测试（不需要真正的数据库或Ollama）
```bash
uv run pytest -q
```
运行400多个测试（有关确切数量，请参见CI日志 — 上方的测试徽章显示通过/失败状态，而不是数量）。大多数测试在没有数据库的情况下运行。一组PostgreSQL集成测试在CI中针对pgvector服务在`pg`标记后运行。覆盖范围包括嵌入、搜索、vault路径安全性、连接池、仪表板身份验证、跨进程锁定、模式迁移、`osm` CLI向导和CI治理。
### `test_dashboard_smoke.py` — 仪表板健康检查（Docker堆栈）
离线静态分析（始终运行 — 不需要服务）+在线HTTP烟雾测试（如果仪表板无法访问，则自动跳过）。
```bash
# 离线 + 在线（必须运行堆栈）
uv run pytest tests/test_dashboard_smoke.py -v
# 针对远程实例
DASHBOARD_URL=http://host:8484 uv run pytest tests/test_dashboard_smoke.py -v
```
检查：JS字符串安全性、DOM元素完整性、`/api/stats`模式、服务健康状况、响应时间和路由。
### `test_setup.py` — 前置条件检查（本地安装）
验证Python依赖项、vault路径、PostgreSQL + pgvector、Ollama和嵌入烟雾测试。直接运行 — 不通过pytest。
```bash
DATABASE_URL="postgresql://localhost/obsidian_brain" \
OBSIDIAN_VAULT="/path/to/your/vault" \
uv run python3 tests/test_setup.py
```
### `test_e2e.py` — 端到端MCP测试（本地安装）
启动服务器，初始化MCP协议，等待索引，运行语义搜索，并验证结果。直接运行 — 不通过pytest。
需要`DATABASE_URL` **或** `POSTGRES_PASSWORD` — 服务器将在没有其中一个的情况下立即退出。
```bash
DATABASE_URL="postgresql://localhost/obsidian_brain" \
OBSIDIAN_VAULT="/path/to/your/vault" \
uv run python3 tests/test_e2e.py
```
## Windows + 网络vault（NFS / SMB）
如果您的vault位于NAS上，并作为驱动器号（`Z:\`）挂载在Windows上，则`osm init`将无法将其绑定到容器中 — Docker Desktop on Windows使用WSL2，而WSL2无法跟随Windows端的网络驱动器进入容器。UNC表单（`\\host\share\...`）被守护进程直接拒绝；驱动器号表单则会静默挂载一个空目录。
**推荐的解决方法：在WSL2中挂载共享文件夹，并将`osm init`指向Linux路径。**
```bash
# 在您的WSL2发行版中（Ubuntu/Debian）
sudo apt install nfs-common
sudo mkdir -p /mnt/obsidian_vault
sudo mount -t nfs <nas-host>:/<export-path> /mnt/obsidian_vault
# 添加到/etc/fstab以在重启后持续
osm init --mode 2 --vault /mnt/obsidian_vault
```
Docker Desktop在WSL2路径上与卷驱动程序的 gymnastics 无缝共享。从v0.5.11开始，`osm init`还会在`docker compose up`被拒绝时快速失败，并指向本节而不是让postgres健康检查超时90秒后。
### 替代方案：本地NFS / CIFS命名卷（`--vault-fs`，v0.5.12+）
如果WSL2不可用，`osm init`可以生成一个`docker-compose.override.yml`，它为每个vault使用NFS或CIFS驱动程序选项的Docker命名卷。vault条目使用协议特定的语法代替主机路径：
```bash
# NFS（一个或多个vault；条目使用host:/export/path）
osm init --mode 3 \
--vault 10.0.0.1:/exports/coredev \
--vault-fs nfs
# CIFS / SMB
osm init --mode 3 \
--vault //nas.local/share/coredev \
--vault-fs cifs \
--vault-cifs-user alice --vault-cifs-pass 'secret'
```
对于多vault，请将每个条目传递给逗号连接的`OBSIDIAN_VAULTS`环境变量（或重复`--vault`）；每个都会生成自己的命名卷（`obsidian_vault_<basename>`）。`osm remove`在拆除时删除这些卷。
限制：NFSv4（无身份验证），SMB（仅用户名/密码）。NFS Kerberos和CIFS凭证文件在v0.5.12中不受支持。WSL2仍然是大多数用户的推荐路径。
## 故障排除
| 症状 | 原因 | 解决方法 |
|---------|-------|-----|
| `uv: command not found` | `uv`未安装或不在PATH中 | 运行`curl -LsSf https://astral.sh/uv/install.sh \| sh`然后重启终端 |
| `Cannot connect to the Docker daemon` | Docker Desktop未运行 | 向导提供自动启动；或手动从应用程序（macOS）/系统托盘（Windows/Linux）启动Docker Desktop |
| `Permission denied: /path/to/vault` | vault路径不可读 Docker | 在macOS上：Docker Desktop → 设置 → 资源 → 文件共享 — 添加vault路径 |
| `ModuleNotFoundError: No module named 'mcp'` | 系统Python而不是venv | 在配置中使用`.venv/bin/python3`，或使用Docker |
| 在Docker中出现`ModuleNotFoundError: No module named 'psycopg2'` | 容器在venv PATH修复之前构建 | `docker compose up -d --build mcp-server` |
| `Search returns 0 results` | 在空表上构建的IVFFlat索引 | 运行`psql obsidian_brain -c "REINDEX INDEX notes_embedding_idx;"` |
| `Vault indexing is in progress — no results yet` | 首次启动索引未完成 | 等待索引完成（查看`docker compose logs -f mcp-server`） |
| `Cannot reach Ollama` | Ollama未运行 | 运行`ollama serve`或`docker compose up ollama` |
| `Skipped <file>: vector must have at least 1 dimension` | Ollama返回空嵌入（空白/小文件） | 预期 — 文件被跳过，索引继续 |
| `Skipped <file>: 500 Server Error` | Ollama内部错误（文件太大或模型问题） | 预期 — 文件被跳过；尝试`ollama pull nomic-embed-text`以刷新模型 |
| `pgvector extension not found` | 未为您的PG版本安装 | 使用Docker，或从源代码构建（参见本地安装） |
| 服务器在启动时崩溃 | 未设置`OBSIDIAN_VAULT` | 在配置或docker compose命令中设置环境变量 |
| Docker容器无法看到vault | 路径错误或缺少卷 | 确保`OBSIDIAN_VAULT`是Docker可访问的绝对路径 |
---
## 本地安装（macOS）
手动安装。仅当您要自己控制每个步骤，而不使用引导安装程序时使用。
### 1. 克隆和安装
```bash
git clone https://github.com/artificemachine/obsidian-semantic-mcp.git && cd obsidian-semantic-mcp
uv sync
```
### 2. 安装系统依赖项
```bash
brew install postgresql@17 pgvector ollama
brew services start postgresql@17
ollama serve &
ollama pull nomic-embed-text
```
> **PostgreSQL 16:** Homebrew的`pgvector`瓶需要pg17或pg18。如果您必须使用pg16，请从源代码构建pgvector：
> ```bash
> cd /tmp
> git clone --branch v0.8.2 --depth 1 https://github.com/pgvector/pgvector.git
> cd pgvector
> make PG_CONFIG=$(brew --prefix postgresql@16)/bin/pg_config
> make install PG_CONFIG=$(brew --prefix postgresql@16)/bin/pg_config
> ```
### 3. 设置数据库
```bash
createdb obsidian_brain
psql obsidian_brain -c "CREATE EXTENSION vector;"
```
### 4. 验证
```bash
DATABASE_URL="postgresql://localhost/obsidian_brain" \
OBSIDIAN_VAULT="/path/to/your/vault" \
uv run python3 tests/test_setup.py
```
### 5. 配置Claude Desktop
将以下内容添加到 `$HOME/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"obsidian-semantic": {
"command": "/absolute/path/to/obsidian-semantic-mcp/scripts/obsidian-semantic-mcp",
"args": [],
"env": {}
}
}
}
```
启动器读取存储库`.env`以进行本地回退，并在可用时自动使用正在运行的Docker服务。
> **重要：** 使用`.venv/bin/python3` — 而不是系统Python。Homebrew Python将没有所需的包。
### 6. 重启Claude Desktop
服务器在第一次运行时索引您的vault，然后自动监视更改。
## 成本
所有内容都在本地运行。没有云API，没有订阅。唯一的成本是数据库的磁盘空间（大多数vault大约为几MB）。
## 文档
完整文档 — 架构、操作手册、设计记录、解释器和事件事后总结 — 索引在[`docs/README.md`](docs/README.md)中。
## 许可证
Apache 2.0
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器