AI导哈

语义搜索服务

一个用于在Obsidian Second Brain vault中进行语义搜索的MCP服务器，使用自托管的Qdrant向量存储和Google Gemini嵌入。

  • by fjacquet
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 fjacquet/vault-rag-mcp

使用说明

金库抹布mcp

MCP服务器用于黑曜石第二大脑库中的语义搜索，使用自托管的Qdrant向量存储和Google Gemini嵌入。

建筑

Claude Code <-> vault-rag MCP server (stdio)
                 |-> Google Gemini gemini-embedding-001 (native 3072d)
                 |-> Qdrant `vault_chunks` collection (3072d, Cosine distance)

混合RAG架构的一部分：

  • 索引：n8n（远程）+Google Gemini API
  • 本地查询：此MCP服务器+Google Gemini API
  • 网络聊天：n8n Vault聊天（AI代理+Gemini原生）或聊天中心（HTTP管道）
  • 散装指数：使用Gemini编写脚本 gemini-embedding-001

同一型号(gemini-embedding-001，原生3072d）确保了矢量兼容性。 向量以具有余弦距离的原生3072维（float32）存储。

不对称任务类型： RETRIEVAL_DOCUMENT 为了索引， RETRIEVAL_QUERY 搜索。

工具

工具 说明
search_vault 在整个保险库中进行语义搜索（查询、限制、para_folder、note_type）
search_glossary 在术语表定义中搜索（3_资源/定义/）
get_note 按文件路径检索笔记的完整内容

先决条件

  • Python>=3.11
  • 紫外线 包管理器
  • Google API密钥（用于Gemini嵌入）
  • Qdrant实例具有 vault_chunks 集合（在第一个索引上自动创建）

设置

# Clone and install
cd ~/Projects/vault-rag-mcp
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your Google API key and Qdrant credentials

环境变量

变量 描述 默认值
QDRANT_URL Qdrant实例URL（HTTPS要求 :443 港口；如果缺少，则自动附加） （必填）
QDRANT_API_KEY Qdrant API密钥 （必需）
GOOGLE_API_KEY Google AI API密钥 （必需）
EMBEDDING_MODEL Gemini嵌入模型 gemini-embedding-001

用法

作为MCP服务器（克劳德代码）

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "vault-rag": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/vault-rag-mcp", "vault-rag-mcp"],
      "env": {
        "QDRANT_URL": "https://your-qdrant-instance.example.com",
        "QDRANT_API_KEY": "your-qdrant-api-key",
        "GOOGLE_API_KEY": "your-google-api-key",
        "EMBEDDING_MODEL": "gemini-embedding-001"
      }
    }
  }
}

重新启动克劳德代码以激活。然后在对话中直接使用这些工具。

批量指数化

通过Google Gemini索引整个黑曜石金库的脚本：

uv run python scripts/bulk_index.py /path/to/vault [--force]

选项：

  • --force ：重新索引所有文件，忽略file_hash缓存

脚本：

  1. 走过金库，跳过 .obsidian/, templates/, .trash/，文件>500 KB
  2. 解析YAML frontmatter（类型、标签、PARA文件夹）
  3. 按H2部分划分块，拆分超大块（>2000个字符）
  4. 通过Google Gemini以50个为一批嵌入（task_type=RETRIEVAL_DOCUMENT）
  5. 使用SHA256 file_hash有效负载升级到Qdrant，用于增量重新运行

在初始批量索引化之后，n8n通过Gemini API处理增量更新。

项目结构

vault-rag-mcp/
├── pyproject.toml              # uv + hatch build config
├── .env.example                # Environment template
├── src/
│   └── vault_rag_mcp/
│       ├── __init__.py
│       ├── server.py           # MCP server (FastMCP, stdio) — 3 tools
│       ├── embeddings.py       # Google Gemini embedding client (native 3072d)
│       └── qdrant_store.py     # Qdrant client + collection operations
├── scripts/
│   └── bulk_index.py           # Bulk indexation via Google Gemini
└── n8n-workflows/              # n8n workflow definitions
    ├── vault-rag-github-indexation.json
    └── vault-rag-chat-hub.json

Qdrant收集

收藏 vault_chunks --3072维的向量，余弦距离。每个点都包含：

  • content --大块文本
  • file_path --从vault根的相对路径
  • chunk_index --文件中的位置
  • para_folder --PARA文件夹（1_项目、2_区域等）
  • note_type --前件类型（备忘录、术语表、操作指南等）
  • file_hash --SHA256用于变化检测
  • metadata --标签、类型、文件夹

点ID是从以下内容导出的确定性UUID 5值 file_path::chunk_index.

有效载荷指数： file_path （关键字）， para_folder （关键字）， note_type （关键字）， chunk_index （整数）。

技术栈

  • MCP-SDK: mcp[cli] 和 FastMCP （stdio传输）
  • 嵌入：谷歌双子座 gemini-embedding-001 通过 google-genai SDK（原生3072d，多语言，2048令牌/文本）
  • 向量数据库：Qdrant（自托管）-- vault_chunks 收藏，3072d余弦距离
  • 构建：紫外线+舱口

相关 MCP