图谱RAG MCP服务器
项目介绍
Graph RAG MCP Server for Obsidian
一个以本地优先的Graph-RAG系统，结合了基于元数据图关系的ChromaDB统一存储和用于智能问答的Gemini 2.5 Flash，适用于你的Obsidian知识库。
🌟 特性
- 📊 统一数据库架构：ChromaDB与基于元数据的图关系，支持语义搜索和图遍历
- 🧠 智能语义分块：尊重Markdown结构（标题、章节、列表、代码块）
- 🎯 PARA分类法：使用项目、领域、资源、归档系统进行AI驱动的组织
- 🤖 RAG驱动的问答：多跳检索，使用Gemini 2.5 Flash
- 🕸️ 图导航：探索反向链接、标签和语义关系
- 🔄 实时同步：文件监视器自动索引
- 🏠 本地优先：所有处理都在本地进行（除了Gemini API调用）
- 📝 多客户端MCP支持：兼容Claude Desktop、Cursor和Raycast
- ⚡ 双传输模式：标准输入输出（stdio）用于Claude Desktop，HTTP用于其他客户端
- 🛠️ 自动安装：单命令设置，带客户端检测
- 🔒 强类型化：整个过程使用Pydantic模型确保可靠性
🎯 支持的MCP客户端
- 🤖 Claude Desktop：完整的stdio集成，自动配置
- 📝 Cursor：HTTP模式，支持MCP扩展
- ⚡ Raycast：HTTP API，自定义扩展模板
- 🔌 任何MCP客户端：标准MCP协议支持（stdio/HTTP）
🏗️ 架构
┌─────────────────┐ ┌─────────────────┐
│ Obsidian │ │ ChromaDB │
│ Vault │───▶│ (统一存储) │
│ │ │ 向量+图 │
└─────────────────┘ │ 元数据 │
│ └─────────────────┘
│ │
│ ▼
│ ┌─────────────────┐
│ │ DSPy │
└─────────────▶│ RAG引擎 │
│ + Gemini 2.5 │
│ (多跳检索) │
└─────────────────┘
│
▼
┌─────────────────┐
│ MCP服务器 │
│ (FastMCP) │
└─────────────────┘
│
▼
┌─────────────────┐
│ Claude Desktop │
│ 集成 │
└─────────────────┘
🚀 快速开始
自动安装（推荐）
使用Claude Desktop、Cursor或Raycast最简单的方法：
# 交互式安装向导
uv run install.py
# 或非交互式，使用你的设置
uv run install.py --vault "/path/to/your/vault" --api-key "your_key"
安装程序会：
- ✅ 检测已安装的MCP客户端（Claude Desktop、Cursor、Raycast）
- ⚙️ 自动配置每个客户端
- 📦 安装所有依赖项
- 🧪 测试安装
- 📝 创建环境配置
手动安装
如果你更喜欢手动设置：
1. 安装uv（如果未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux
2. 安装依赖项
uv sync
3. 配置环境
cp configs/.env.example .env
# 编辑.env并添加你的GEMINI_API_KEY和知识库路径
4. 索引你的知识库
# 完全索引（统一ChromaDB存储）
uv run scripts/reindex.py all
# 检查索引状态
uv run scripts/reindex.py status
5. 配置你的MCP客户端
Claude Desktop（stdio模式）：
{
"mcpServers": {
"graph-rag-obsidian": {
"command": "uvx",
"args": ["--python", "3.13", "--from", ".", "graph-rag-mcp-stdio"],
"cwd": "/path/to/graph-rag-mcp-server",
"env": {
"GEMINI_API_KEY": "your_api_key_here",
"OBSIDIAN_RAG_VAULTS": "/path/to/your/vault"
}
}
}
}
Cursor（HTTP模式）：
# 启动HTTP服务器
uv run graph-rag-mcp-http
# 配置Cursor MCP扩展以使用http://localhost:8765
Raycast（HTTP模式）：
# 启动HTTP服务器
uv run graph-rag-mcp-http
# 安装生成的Raycast扩展
详细配置说明，请参阅SETUP.md。
🛠️ 可用命令
MCP服务器模式
# 交互式安装向导
uv run install.py
# Claude Desktop（stdio模式）
uvx --python 3.13 --from . graph-rag-mcp-stdio
# Cursor/Raycast（HTTP模式）
uv run graph-rag-mcp-http
# 带自定义端口的HTTP
uv run graph-rag-mcp-http --port 9000
# 直接stdio运行（替代方案）
uv run main.py # stdio模式
uv run src/mcp_server.py # stdio模式
索引脚本
# 完全索引
uv run scripts/reindex.py all
# ChromaDB统一存储
uv run scripts/reindex.py unified
# 检查状态
uv run scripts/reindex.py status
实时监控
# 启动文件监视器
uv run scripts/reindex_watch.py start
# 测试文件检测
uv run scripts/reindex_watch.py test
PARA分类法丰富
使用DSPy增强你的知识库，通过智能PARA系统分类：
# 分析当前知识库分类状态
uv run scripts/enrich_para_taxonomy.py analyze --sample 100
# 预览丰富（干跑）在样本笔记上
uv run scripts/enrich_para_taxonomy.py enrich --limit 10 --dry-run
# 应用于特定笔记
uv run scripts/enrich_para_taxonomy.py enrich "path/to/note.md" --apply
# 使用过滤器批量丰富
uv run scripts/enrich_para_taxonomy.py enrich --limit 50 --folder "Projects" --apply
# 整个知识库丰富（新！）
# 预览整个知识库丰富
uv run scripts/enrich_para_taxonomy.py enrich-all --dry-run
# 应用于整个知识库（默认跳过已丰富的）
uv run scripts/enrich_para_taxonomy.py enrich-all --apply
# 强制重新丰富整个知识库
uv run scripts/enrich_para_taxonomy.py enrich-all --apply --force-all
# 自定义大型知识库的批处理大小
uv run scripts/enrich_para_taxonomy.py enrich-all --apply --batch-size 25
PARA分类功能：
- 🎯 智能分类：使用Gemini 2.5 Flash将笔记分类到项目、领域、资源、归档
- 🏷️ 层次标签：建议结构化的标签如
#para/project/ai/automation - 🔗 关系发现：找到相关笔记之间的潜在链接，并进行验证
- 💡 概念提取：识别关键概念和主题
- 🛡️ 安全更新：仅添加前言，从不修改内容
- 📊 信心评分：提供分类的理由和信心评分
- ⚡ 批处理：高效处理整个知识库，可配置批处理大小
- 🔄 智能去重：避免重复处理已丰富的笔记
🔧 MCP工具
该服务器为Claude提供了以下工具：
搜索&问答
search_notes：跨知识库的向量搜索answer_question：带引用的RAG驱动问答graph_neighbors：通过图查找相关笔记get_subgraph：提取笔记子图
笔记操作
create_note：创建带有自动丰富前言的新笔记list_notes：浏览知识库内容read_note：获取完整笔记内容get_note_properties：读取前言update_note_properties：修改前言add_content_to_note：追加内容
图导航
get_backlinks：查找指向目标的笔记get_notes_by_tag：按标签查找笔记
管理
archive_note：将笔记移至归档create_folder：创建目录reindex_vault：重新索引统一ChromaDB存储enrich_notes：对笔记应用PARA分类法丰富
⚙️ 配置
.env中的关键设置：
# 必需
GEMINI_API_KEY=your_key_here
# ChromaDB配置
OBSIDIAN_RAG_CHROMA_DIR=/custom/path/to/.chroma_db
OBSIDIAN_RAG_COLLECTION=vault_collection
# 可选定制
OBSIDIAN_RAG_EMBEDDING_MODEL=all-MiniLM-L6-v2
OBSIDIAN_RAG_GEMINI_MODEL=gemini-2.5-flash
# 语义分块配置
OBSIDIAN_RAG_CHUNK_STRATEGY=semantic # 或“character”用于简单的分块
OBSIDIAN_RAG_SEMANTIC_MIN_CHUNK_SIZE=100
OBSIDIAN_RAG_SEMANTIC_MAX_CHUNK_SIZE=3000
OBSIDIAN_RAG_SEMANTIC_MERGE_THRESHOLD=200
🏃♂️ 使用示例
搜索你的知识库
# 向量搜索
results = search_notes("机器学习算法", k=5)
# 带上下文的问答
answer = answer_question("我对transformers了解到了什么？")
探索关系
# 查找相关笔记
neighbors = graph_neighbors("深度学习", depth=2)
# 获取反向链接
backlinks = get_backlinks("神经网络")
# 按标签查找
tagged_notes = get_notes_by_tag("ai")
管理笔记
# 创建带有自动丰富的新笔记
note = create_note(
title="机器学习突破",
content="# 关键发现\n\n发现了新的优化技术...",
folder="研究",
tags=["ml", "优化"],
para_type="project", # PARA分类提示
enrich=True # 应用AI丰富
)
# 读取笔记
content = read_note("研究/AI进展.md")
# 更新属性
update_note_properties("研究/AI进展.md", {
"status": "完成",
"tags": ["ai", "研究", "已完成"]
})
创建带有自动丰富的笔记
create_note工具创建格式正确的Obsidian笔记，包括：
- 清晰的YAML前言
- 自动PARA分类（如果有内容）
- 智能标签建议
- 潜在链接发现
- 时间戳和元数据
示例创建的笔记：
---
created: '2025-08-23T20:30:00.000000'
modified: '2025-08-23T20:30:00.000000'
para_type: project
para_category: ai/research
para_confidence: 0.85
key_concepts:
- 机器学习优化
- 梯度下降改进
- 性能基准测试
tags:
- ml
- 优化
- para/project
- para/project/ai/research
- tech/ai/ml/optimization
potential_links:
- '[[优化技术]]'
- '[[2025年研究日志]]'
enrichment_version: '1.0'
last_enriched: '2025-08-23T20:30:00.000000'
enrichment_model: gemini-2.5-flash
---
# 机器学习突破
你的内容在这里...
PARA丰富工作流程
步骤1：分析你的知识库
uv run scripts/enrich_para_taxonomy.py analyze --sample 100
显示当前分类状态和丰富潜力。
步骤2：在子集上测试（干跑）
uv run scripts/enrich_para_taxonomy.py enrich --limit 5 --dry-run
预览分类而不做更改。
步骤3：应用丰富
# 从小规模开始
uv run scripts/enrich_para_taxonomy.py enrich --limit 20 --apply
# 扩大规模
uv run scripts/enrich_para_taxonomy.py enrich --limit 100 --apply
示例丰富后的笔记：
---
para_type: project
para_category: AI/自动化
para_confidence: 0.9
key_concepts:
- AI代理开发
- 计算机使用自动化
- 基于地面的AI系统
tags:
- "#project/ai/自动化"
- "#area/ai/开发"
potential_links:
- "相关项目名称"
enrichment_version: "1.0"
last_enriched: "2025-08-23T17:59:32"
---
# 你的原始笔记内容保持不变
🔍 工作原理
- 文件解析：提取Markdown内容、前言、维基链接和标签
- 语义分块：基于Markdown结构（标题、章节、列表）的智能分块
- 向量索引：将语义分块及其嵌入存储在ChromaDB中
- 图元数据：将笔记、链接、标签和分块关系作为ChromaDB元数据存储
- PARA分类：使用DSPy + Gemini将笔记分类到项目、领域、资源、归档
- RAG流水线：结合向量搜索和图遍历的多跳检索
- MCP接口：通过模型上下文协议暴露所有功能
🆕 新特性
统一的ChromaDB架构（最新更新！）
- ⚡ 简化的架构：单一数据库用于向量搜索和图关系
- 🗄️ 基于元数据的图：利用ChromaDB的原生元数据能力高效存储图
- 🔧 合并的数据：向量嵌入和图关系一起存储，以实现最佳查询性能
- 📦 减少依赖：无需单独的RDF库或存储
- 🚀 性能：通过直接元数据访问简化查询
- 💾 高效存储：单一存储，优化嵌入和元数据存储
增强的PARA分类法
- 🤖 AI驱动的分类：自动分类到项目、领域、资源、归档
- 🏷️ 智能标签：层次标签如
#para/project/ai/自动化 - 🔗 验证过的维基链接：仅建议链接到你知识库中存在的笔记
- 📊 批处理：使用可配置的批处理大小处理整个知识库
- 🎯 Obsidian原生：干净的YAML前言，无Markdown格式
ChromaDB元数据模式
系统将图关系存储为ChromaDB元数据：
# 笔记级元数据
metadata = {
"note_id": "my_note",
"title": "我的笔记标题",
"path": "/path/to/note.md",
"tags": "重要,ai,项目",
"links_to": "其他笔记,相关笔记",
"backlinks_from": "来源笔记,另一个笔记",
"vault": "我的知识库"
}
# 分块级元数据（语义分块）
chunk_metadata = {
"chunk_id": "my_note#chunk_0",
"chunk_type": "章节",
"header_text": "介绍",
"header_level": 2,
"importance_score": 0.8,
"sequential_next": "my_note#chunk_1",
"sequential_prev": "",
"parent_chunk": "my_note#header_0",
"child_chunks": "my_note#chunk_1,my_note#chunk_2",
"sibling_chunks": "my_note#chunk_3",
"semantic_chunk": True
}
🛡️ 安全与隐私
- 本地优先：所有数据处理都在你的机器上进行
- API调用：仅用于文本生成的Gemini API（可选）
- 无数据泄露：知识库内容从未离开你的控制
- 路径验证：防止目录遍历攻击
🧪 测试
测试套件（pytest）
安装测试依赖项并运行套件：
# 使用uv（推荐）
uv sync --extra test
uv run pytest -q
# 或使用本地虚拟环境
PYTHONPATH=. .venv/bin/pytest -q
常见调用：
# 仅单元/集成
PYTHONPATH=. .venv/bin/pytest tests/unit -q
PYTHONPATH=. .venv/bin/pytest tests/integration -q
# 覆盖率（阈值配置在pytest.ini中）
PYTHONPATH=. .venv/bin/pytest --cov -q
# 标记
pytest -m unit
pytest -m integration
pytest -m "not slow"
注意事项