Second Brain (second-brain)

黑曜石RAG MCP

本地第一个检索增强生成（RAG）管道 黑曜石 拱顶。对笔记进行一次索引，然后从命令行或通过任何兼容MCP的AI客户端（Claude Desktop、Cursor、VS Code Copilot等）进行语义查询。

特性

• 混合检索 --通过交互排名融合将语义向量搜索（Qdrant）与全文关键字搜索（SQLite FTS5）相结合
• 增量索引 --仅重新索引自上次同步以来更改的文件
• MCP工具界面 --将您的保管库作为任何MCP客户端都可以调用的工具公开
• 本地优先 --所有嵌入和存储都在您的机器上运行；什么都没有留下
• 可配置分块 --调整每个保管库的块大小、重叠和全局排除
• 隐私控制 --在敏感模式到达索引之前对其进行编辑

先决条件

Qdrant通过嵌入式运行 qdrant-client --不需要单独的服务器。

安装

选项A-pipx（推荐给最终用户）

直接从GitHub安装并使CLI全局可用：

pipx install git+https://github.com/AngelCantugr/second-brain.git

或者从本地克隆：

git clone https://github.com/AngelCantugr/second-brain.git
cd second-brain
pipx install .

选项B--uv（建议开发）

git clone https://github.com/AngelCantugr/second-brain.git
cd second-brain
uv sync --dev

然后在所有命令前加上 uv run:

uv run obsidian-rag --help

选项C-pip在虚拟环境中

git clone https://github.com/AngelCantugr/second-brain.git
cd second-brain
python -m venv .venv && source .venv/bin/activate
pip install .

CLI使用情况

将CLI指向包含（或将包含）黑曜石保管库的任何目录。

1.初始化

创建 rag_config.toml 和一个 data/ 当前工作目录中的目录：

cd ~/my-obsidian-vault
obsidian-rag init

使用 --force 要重新生成现有配置，请执行以下操作：

obsidian-rag init --force

2.同步保管库

# First-time full index
obsidian-rag sync --mode full

# Pick up recent changes
obsidian-rag sync --mode incremental

# Re-index one file
obsidian-rag sync --mode file --file-path "Projects/my-note.md"

3.搜索和查询

# Hybrid search — returns scored chunks
obsidian-rag search "async rust patterns"

# Query — returns an answer draft with citations
obsidian-rag query "What are my notes on system design?"

# Adjust result count
obsidian-rag query "project ideas" --top-k 5

4.作战命令

# Runtime status (model, index size, last sync)
obsidian-rag status

# Health check (Qdrant, Ollama, FTS)
obsidian-rag health

使用自定义配置路径

所有命令接受 --config 指向非默认配置文件：

obsidian-rag --config ~/vaults/work/rag_config.toml sync --mode full

MCP 服务器

MCP服务器将您的保管库公开为任何兼容的AI客户端的可调用工具。

启动服务器

obsidian-rag-mcp --config /absolute/path/to/rag_config.toml

可用的MCP工具

克劳德桌面版

将以下内容添加到您的 claude_desktop_config.json （通常 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
	"mcpServers": {
		"obsidian-rag": {
			"command": "obsidian-rag-mcp",
			"args": ["--config", "/absolute/path/to/your/vault/rag_config.toml"]
		}
	}
}

如果您安装了 uv，使用venv二进制文件的完整路径： "/path/to/second-brain/.venv/bin/obsidian-rag-mcp"

VS代码（GitHub副本）

添加到您的 .vscode/mcp.json 或用户级MCP设置：

{
	"servers": {
		"obsidian-rag": {
			"type": "stdio",
			"command": "obsidian-rag-mcp",
			"args": ["--config", "/absolute/path/to/your/vault/rag_config.toml"]
		}
	}
}

配置参考

obsidian-rag init 生成a rag_config.toml 使用这些默认值：

# Path to your Obsidian vault (or any markdown directory)
vault_path = "$CWD"

# Local storage — relative paths resolve from the config file's directory
qdrant_path     = "$CWD/data/qdrant"
fts_path        = "$CWD/data/fts.sqlite"
sync_state_path = "$CWD/data/sync_state.sqlite"

# Qdrant collection name
collection_name = "obsidian_chunks"

# Ollama settings
ollama_url      = "http://127.0.0.1:11434"
embedding_model = "nomic-embed-text"

# Chunking
chunk_size    = 500
chunk_overlap = 80

# Auto-watch vault for file changes (used by long-running processes)
watch_enabled = true

# Glob patterns excluded from indexing
exclude_globs = [".obsidian/**", ".git/**", "Templates/**"]

# Max chunks returned per query
max_context_chunks = 8

# Regex patterns to redact from chunk text before indexing
redact_patterns = []

$CWD 解析到当时的工作目录 init 正在运行。标准 ~ 并且在所有路径字段中都支持环境变量扩展。

项目结构

obsidian_rag/
├── cli.py           # CLI entrypoint (obsidian-rag)
├── mcp_server.py    # MCP server entrypoint (obsidian-rag-mcp)
├── service.py       # High-level facade shared by CLI and MCP
├── indexer.py       # Orchestrates parse, chunk, embed, store
├── parser.py        # Markdown + frontmatter parser
├── chunker.py       # Text chunking with overlap
├── embedder.py      # Ollama embedding client
├── vector_store.py  # Qdrant vector store wrapper
├── keyword_store.py # SQLite FTS5 keyword store
├── retrieval.py     # Reciprocal Rank Fusion merge
├── sync_state.py    # Incremental sync state tracking
├── watcher.py       # File-system watcher (watchfiles)
└── config.py        # TOML config loader

发展

uv sync --dev
uv run pytest -q

进一步阅读

• RAG初学者指南 --从第一性原理看管道是如何工作的
• 端到端查询跟踪 --按照查询遍历每一层