Name: 图向量混合检索服务器
Author: AN-SWAPNIL

使用说明

GraphRAG MCP服务器

一种用于查询混合图形和矢量数据库系统的模型上下文协议服务器，结合Neo4j（图形数据库）和Qdrant（矢量数据库）进行强大的语义和基于图形的文档检索。

概述

GraphRAG MCP提供了大型语言模型和混合检索系统之间的无缝集成，该系统利用了图形数据库（Neo4j）和向量数据库（Qdrant）的优势。这使得：

语义搜索 通过文档嵌入
基于图的上下文扩展 遵循文档内部关系
混合搜索 向量相似性与图关系的结合
基于页面的分块 通过智能合并实现最优检索
精确的页面导航 支持合并页面
与Claude、VS Code、Cursor和其他启用MCP的客户端完全集成

该项目遵循模型上下文协议规范，使其与任何支持MCP的客户端兼容。

特性

语义搜索 使用句子嵌入（全MiniLM-L6-v2）和Qdrant
基于图的上下文扩展 使用Neo4j文档内关系
混合搜索 结合这两种方法以获得全面的结果
页面级检索 -从特定页面或页面范围获取准确内容
智能页面合并 -在索引过程中自动合并小页面
文档筛选 -在特定文档中搜索
MCP工具和资源 实现无缝LLM集成
Docker Compose 易于部署的设置
实用脚本 用于索引、测试和诊断

先决条件

Python 3.12+ （MCP服务器需要）
Docker&Docker编写 （建议用于轻松设置数据库）

紫外线 包管理器（用于依赖关系管理）

安装紫外线：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

安装

快速入门（推荐）

克隆此存储库：

git clone https://github.com/AN-SWAPNIL/graphrag_mcp.git
cd graphrag_mcp

安装Python依赖项：
```
uv install
```

配置环境变量：

复制示例环境文件并根据需要进行自定义：

# Linux/macOS
cp .env.example .env

# Windows
copy .env.example .env

默认 .env 配置：

# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# Qdrant Configuration
QDRANT_HOST=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION=document_chunks

# HuggingFace Token (optional, for downloading models)
HF_TOKEN=your_token_here

使用Docker Compose启动数据库：
```
docker-compose up -d
```
这将开始：
- 端口7474（HTTP）和7687（Bolt）上的Neo4j
- 端口6333（HTTP）和6334（gRPC）上的Qdrant
等待约20秒，以便数据库初始化。
为您的文档建立索引：

将标记文件放置在 specs/ 目录，然后运行：
```
uv run index_markdown.py
```
此脚本：
- 按页面边界拆分文档
- 智能合并小页面
- 使用句子变换器创建嵌入
- 在Qdrant中存储向量
- 在Neo4j中构建图形关系
运行MCP服务器：
```
uv run main.py
```

Windows快速入门（批处理脚本）

对于Windows用户，提供了方便的批处理脚本：

# Start everything (Docker + MCP server)
mcp_start.bat

# Stop everything
mcp_stop.bat

手动设置（无Docker）

如果你更喜欢在没有Docker的情况下运行Neo4j和Qdrant：

Neo4j设置

使用Docker（单容器）：

docker run \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  -v $HOME/neo4j/data:/data \
  -v $HOME/neo4j/logs:/logs \
  neo4j:latest

或在本地安装：
- 下载自 neo4j.com/下载
- 遵循平台特定的安装说明
- 将密码设置为 password 或更新 .env 文件

Qdrant设置

使用Docker（单容器）：

docker run -p 6333:6333 -p 6334:6334 \
  -v $HOME/qdrant/storage:/qdrant/storage \
  qdrant/qdrant

或在本地安装：
- 下载自 qdrant.tech/文档/快速启动
- 按照平台的安装说明进行操作

项目结构

graphrag_mcp/
├── graphrag_mcp/              # Main package
│   ├── __init__.py
│   └── documentation_tool.py  # Core hybrid search implementation
├── specs/                     # Your markdown documents go here
├── .env                       # Environment configuration (create from .env.example)
├── .env.example               # Example environment variables
├── docker-compose.yml         # Docker setup for Neo4j + Qdrant
├── main.py                    # MCP server entry point
├── server.py                  # MCP tool and resource definitions
├── index_markdown.py          # Document indexing script (page-based chunking)
├── clear.py                   # Utility to clear all indexed data
├── test_graphrag.py           # Test script for functionality
├── diagnose_data.py           # Diagnostic script for data validation
├── mcp_start.bat              # Windows: Start Docker + MCP server
├── mcp_stop.bat               # Windows: Stop all services
└── pyproject.toml             # Python dependencies

实用脚本

索引文档： `index_markdown.py`

使用高级基于页面的分块对markdown文件进行索引：

uv run index_markdown.py

特征：

按“第N页”标记拆分文档
将少于50个单词的页面合并到相邻页面中
创建语义嵌入（384个dim向量）
使用三种关系类型构建Neo4j图：
- NEXT_PAGE：顺序页面流
- RELATED_TO：文档中的语义相似性
- CONTAINS：文档到页面的关系

输出：

存储在Qdrant中的矢量和页面元数据
图形节点(:Document, :Page)在Neo4j中
合并和关系的详细统计数据

测试： `test_graphrag.py`

快速功能测试：

uv run test_graphrag.py

测验：

向量搜索
具有上下文扩展的混合搜索
文档内上下文检索

诊断： `diagnose_data.py`

验证您的索引数据：

uv run diagnose_data.py

检查：

Qdrant有效载荷结构
Neo4j文档和页面计数
关系统计
来自两个数据库的示例数据

清除数据： `clear.py`

删除所有索引数据（小心使用）：

uv run clear.py

这将删除：

所有Neo4j节点和关系
整个Qdrant系列

与MCP客户端集成

GraphRAG MCP服务器可与任何兼容MCP的客户端配合使用，包括VS Code、Claude Desktop和Cursor。

VS代码集成

打开VS代码设置 搜索“MCP”或直接编辑MCP配置文件。
添加服务器配置 致你的 mcp.json 文件：

位置（Windows）：
```
C:\Users\<YourUsername>\AppData\Roaming\Code\User\mcp.json
```
位置（macOS/Linux）：
```
~/.config/Code/User/mcp.json
```

配置：

{
  "servers": {
    "my-graph-rag-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "D:\\Codes\\mcp\\graphrag_mcp", // Change to your path
        "run",
        "main.py"
      ]
    }
  }
}

对于类Unix系统（macOS/Linux）：

{
  "servers": {
    "my-graph-rag-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/graphrag_mcp", "run", "main.py"]
    }
  }
}

重新启动VS代码 -MCP服务器现在将可用于GitHub Copilot Chat。

Claude桌面集成

找到您的Claude配置文件：

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

窗户：

%APPDATA%\Claude\claude_desktop_config.json

添加服务器：

{
  "mcpServers": {
    "GraphRAG": {
      "command": "uv",
      "args": ["--directory", "/path/to/graphrag_mcp", "run", "main.py"]
    }
  }
}

重新启动克劳德桌面

光标集成

找到您的Cursor配置文件：

macOS/Linux：
```
~/.cursor/mcp.json
```
窗户：
```
%APPDATA%\Cursor\mcp.json
```

添加配置：

{
  "mcpServers": {
    "GraphRAG": {
      "command": "uv",
      "args": ["--directory", "/path/to/graphrag_mcp", "run", "main.py"]
    }
  }
}

重新启动游标

用法

MCP工具

服务器提供 5个强大的工具 对于LLM集成：

1. `search_documentation` -语义向量搜索

使用纯向量相似度搜索文档。

参数：

query （str）：自然语言查询
limit （int，默认值=5）：返回的最大块数
doc_filter （str，可选）：按文档ID筛选（例如，“application_spec”、“core_spec”）

例子：

result = search_documentation(
    query="How does authentication work?",
    limit=5,
    doc_filter="core_spec"
)

退货：

{
  "query": "How does authentication work?",
  "chunks": [
    {
      "doc": "core_spec",
      "chunk_idx": 15,
      "page_num": 42,
      "page_range": [42],
      "text": "Authentication is handled via...",
      "score": 0.87
    }
  ],
  "count": 5,
  "search_type": "vector_search"
}

2. `hybrid_search` -矢量+图形上下文

使用文档内关系将语义搜索与基于图的上下文扩展相结合。

参数：

query （str）：自然语言查询
limit （int，默认值=5）：向量搜索中的最大种子块
doc_filter （str，可选）：按文档ID筛选
expand_context （bool，默认值=True）：丰富图形关系

例子：

result = hybrid_search(
    query="API endpoints and authentication",
    limit=5,
    doc_filter=None,
    expand_context=True
)

退货： 同 search_documentation，加上其他关系数据：

{
  "chunks": [
    {
      "doc": "core_spec",
      "chunk_idx": 15,
      "page_num": 42,
      "text": "...",
      "score": 0.87,
      "related_next": [{ "chunk_idx": 16, "page_num": 43, "text": "..." }],
      "related_previous": [{ "chunk_idx": 14, "page_num": 41, "text": "..." }],
      "related_discussing": [
        {
          "chunk_idx": 89,
          "page_num": 234,
          "text": "...",
          "keywords": ["API", "auth"]
        }
      ]
    }
  ],
  "expanded_with_context": true
}

3. `get_page` -检索特定页面

从特定页面或页面范围获取确切内容。自动处理合并的页面。

参数：

doc_id （str）：文档标识符（例如，“core_spec”）
start_page （int）：要检索的页码
end_page （int，可选）：页面范围结束（如果请求多个页面）

示例：

# Single page
result = get_page(doc_id='core_spec', start_page=494)

# Page range
result = get_page(doc_id='core_spec', start_page=494, end_page=500)

退货：

{
  "doc_id": "core_spec",
  "start_page": 494,
  "end_page": 494,
  "content": "Page 494\n\nFull text content...",
  "word_count": 523,
  "page_range": [494],
  "is_range": false,
  "pages_retrieved": 1,
  "is_merged": false,
  "next_page": { "page_num": 495, "page_range": [495] },
  "prev_page": { "page_num": 493, "page_range": [493] },
  "related_pages": [
    { "chunk_idx": 120, "page_num": 315, "keywords": ["shared", "topic"] }
  ]
}

合并页面注意事项： 如果在索引过程中将页面2合并到页面1-3中，则查询页面2将返回合并的块 page_range: [1, 2, 3] 和 is_merged: true.

4. `get_document_info` -目录与统计

获取前N页（通常是目录）和文档统计信息。

参数：

doc_id （str）：文档标识符
max_pages （int，默认值=20）：要返回的初始页数

例子：

result = get_document_info(doc_id='core_spec', max_pages=20)

退货：

{
  "doc_id": "core_spec",
  "chunks": [
    { "chunk_idx": 0, "page_num": 1, "page_range": [1, 2, 3], "text": "..." },
    { "chunk_idx": 1, "page_num": 4, "page_range": [4], "text": "..." }
  ],
  "stats": {
    "total_chunks": 523,
    "merged_chunks": 45,
    "next_relationships": 522,
    "discusses_relationships": 1847,
    "total_relationships": 2369
  },
  "max_pages_returned": 20,
  "is_truncated": true
}

MCP资源

服务器暴露 3资源 有关系统信息：

1. `https://graphrag.db/schema/neo4j`

Neo4j图形模式信息包括：

节点标签(:Document, :Page)
关系类型(NEXT_PAGE, RELATED_TO, CONTAINS)
属性密钥
按标签统计节点数

2. `https://graphrag.db/collection/qdrant`

Qdrant矢量采集信息：

集合名称
矢量计数
矢量维度（384）
距离度量（余弦）

3. `https://graphrag.db/documents/list`

所有索引文档及其ID和来源的列表。

运作原理

基于页面的分块与智能合并

索引过程(index_markdown.py)使用智能组块策略：

页面检测： 在“第N页”标记处拆分文档
智能合并： 小于50个单词的页面会自动与相邻页面合并
元数据保存： 即使在合并后也会跟踪原始页码和范围
质量保证： 确保所有块都符合最小单词阈值

例子：

Page 1 (30 words) →
Page 2 (25 words) → Merged into single chunk: pages [1, 2, 3]
Page 3 (40 words) →

Page 4 (150 words) → Standalone chunk: page [4]

图表关系

三种类型的关系将每个文档中的页面连接起来：

NEXT_PAGE -顺序流

Page 1 -[NEXT_PAGE]-> Page 2 -[NEXT_PAGE]-> Page 3

RELATED_TO -语义相似度（余弦相似度>阈值）

Page 5 -[RELATED_TO {keywords: [...], similarity: 0.87}]-> Page 89

CONTAINS -文档所有权

Document -[CONTAINS]-> Page 1, Page 2, Page 3, ...

混合搜索过程

矢量搜索： 查询→ 嵌入→ Qdrant相似性搜索→ 前K块
图形扩展： 对于每个块，检索：
- 顺序上下文（上一页/下一页）
- 同一文档中语义相关的页面
丰富： 将结果与图形上下文相结合，以获得全面的答案

故障排除

连接问题

问题： 无法连接到Neo4j或Qdrant

解决：

确保Docker容器正在运行： docker ps
检查端口是否可用： netstat -an | grep 7687 （Neo4j）或 netstat -an | grep 6333 （Qdrant）
重新启动容器： docker-compose restart
检查日志： docker-compose logs neo4j 或 docker-compose logs qdrant

空搜索结果

问题： 搜索未返回任何结果

解决：

验证数据是否已编入索引： uv run diagnose_data.py
在Neo4j中检查文档计数：访问 http://localhost:7474 （Neo4j浏览器）
重新索引文档： uv run clear.py 然后 uv run index_markdown.py
确保文件在 specs/ 目录

缺少的依赖

问题： 导入错误或缺少包

解决：

重新安装依赖关系： uv install
检查Python版本： python --version （必须为3.12+）
验证是否安装了紫外线： uv --version

数据库身份验证

问题： Neo4j身份验证失败

解决：

验证中的凭据 .env 文件匹配Neo4j设置
默认凭据：用户名=neo4j，密码=password
通过Neo4j浏览器重置Neo4j密码： http://localhost:7474

端口冲突

问题： Docker容器因端口冲突而无法启动

解决：

检查端口的使用情况：

# Windows
netstat -ano | findstr :7687
netstat -ano | findstr :6333

# Linux/macOS
lsof -i :7687
lsof -i :6333

停止冲突的服务或更改中的端口 docker-compose.yml

未检测到MCP服务器

问题： MCP客户端看不到服务器

解决：

验证 mcp.json 路径适合您的操作系统
检查JSON语法是否有效
确保 uv 在您的系统PATH中
完全重新启动MCP客户端
检查服务器登录 graphrag.log

高级用法

自定义文档索引

要为自己的文档建立索引，请执行以下操作：

准备文件：
- 将标记文件放入 specs/ 目录
- 确保页面标记存在： Page N 在独立线路上
- 或修改 index_markdown.py 适用于不同格式

调整分块参数 在 index_markdown.py:

MIN_WORDS = 50  # Minimum words per chunk
SIMILARITY_THRESHOLD = 3  # For RELATED_TO relationships

运行索引：
```
uv run index_markdown.py
```

程序化使用

直接在Python中使用该工具：

from graphrag_mcp.documentation_tool import DocumentationGPTTool

tool = DocumentationGPTTool()

# Vector search
results = tool.search_documentation(
    query="authentication mechanisms",
    limit=5,
    doc_filter="core_spec"
)

# Hybrid search
results = tool.hybrid_search(
    query="API design patterns",
    limit=10,
    expand_context=True
)

# Get specific page
page = tool.get_page_content(
    doc_id="core_spec",
    start_page=494,
    end_page=500
)

# Get document info
info = tool.get_document_info(
    doc_id="application_spec",
    max_pages=20
)

# Clean up
tool.close()

直接查询Neo4j

访问Neo4j浏览器 http://localhost:7474:

// Find all documents
MATCH (d:Document) RETURN d

// Find pages in a documentMATCH (d:Document {id: 'core_spec'})-[:CONTAINS]->(p:Page)
RETURN p.page_num, p.page_range, p.text
ORDER BY p.page_num

// Find semantically related pages
MATCH (p1:Page)-[r:RELATED_TO]->(p2:Page)
WHERE p1.doc_id = 'core_spec'
RETURN p1.page_num, p2.page_num, r.keywords, r.similarity
ORDER BY r.similarity DESC

// Find page sequence
MATCH path = (p:Page)-[:NEXT_PAGE*1..5]->(next:Page)
WHERE p.page_num = 1 AND p.doc_id = 'core_spec'
RETURN path

性能考量

索引时间： 每页约1-2秒（取决于页面大小和合并）
搜索延迟：
- 矢量搜索：~50-100ms，5个结果
- 混合搜索：~150-250ms（包括图遍历）
- 页面检索：~20-50ms
内存使用情况：
- 嵌入型号：~100MB RAM
- Neo4j：~500MB-2GB（随数据缩放）
- Qdrant:~200MB-1GB（带矢量的刻度）

优化提示：

使用 doc_filter 缩小搜索范围
调整 limit 基于需求的参数
集 expand_context=False 更快的hybrid_search
仅索引必要的文件

贡献

欢迎投稿！以下是您可以提供帮助的方式：

报告错误： 打开一个关于复制步骤的问题
建议功能： 描述您的用例和建议的解决方案
提交拉取请求：
- 分叉存储库
- 创建要素分支： git checkout -b feature/amazing-feature
- 提交更改： git commit -m 'Add amazing feature'
- 推送到分支： git push origin feature/amazing-feature
- 打开拉取请求

开发设置

# Clone your fork
git clone https://github.com/YOUR_USERNAME/graphrag_mcp.git
cd graphrag_mcp

# Install with dev dependencies
uv install --dev

# Run tests
uv run pytest

# Run diagnostic checks
uv run diagnose_data.py

许可证

MIT许可证

特此免费向任何获得副本的人授予许可本软件和相关文档文件（“软件”），以处理在软件中不受限制，包括但不限于权利使用、复制、修改、合并、发布、分发、再许可和/或销售软件的副本，并允许软件的接收者根据以下条件提供：

软件按“原样”提供，不提供任何形式的明示或明示担保隐含的，包括但不限于适销性保证，适用于特定目的且不造成伤害。在任何情况下作者或版权持有人对任何索赔、损害赔偿或其他因以下原因产生的责任，无论是在合同、侵权或其他诉讼中，出于或与软件、使用或其他交易有关软件。

归因与致谢

这个项目是原始作品的一个分支和重要扩展 莱利·莱姆 (rileylemm/graphrag_mcp).

此叉子的增强功能：

Docker Compose设置，便于部署
基于页面的分块与智能合并算法
其他MCP工具(get_page, get_document_info)
文档过滤功能
用于自动化的Windows批处理脚本
全面的实用程序脚本（诊断、测试、清除）
扩展文档和示例
VS代码MCP集成

原始概念： 莱利·莱姆
扩展人： 安-斯瓦普尼(GitHub)

内置：

模型上下文协议 -LLM集成框架
Neo4j -图形数据库
Qdrant -矢量数据库
句子转换 -嵌入模型
紫外线 -快速Python包管理器

使用说明

GraphRAG MCP服务器

概述

特性

先决条件

安装

快速入门（推荐）

Windows快速入门（批处理脚本）

手动设置（无Docker）

Neo4j设置

Qdrant设置

项目结构

实用脚本

索引文档： index_markdown.py

测试： test_graphrag.py

诊断： diagnose_data.py

清除数据： clear.py

与MCP客户端集成

VS代码集成

Claude桌面集成

光标集成

用法

MCP工具

1. search_documentation -语义向量搜索

2. hybrid_search -矢量+图形上下文

3. get_page -检索特定页面

4. get_document_info -目录与统计

MCP资源

1. https://graphrag.db/schema/neo4j

2. https://graphrag.db/collection/qdrant

3. https://graphrag.db/documents/list

运作原理

基于页面的分块与智能合并

图表关系

混合搜索过程

故障排除

连接问题

空搜索结果

缺少的依赖

数据库身份验证

端口冲突

未检测到MCP服务器

高级用法

自定义文档索引

程序化使用

直接查询Neo4j

性能考量

贡献

开发设置

许可证

归因与致谢

相关 MCP

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

Meilisearch MCP 搜索服务器

本地LLM模型控制协议

文档搜索服务

索引文档： `index_markdown.py`

测试： `test_graphrag.py`

诊断： `diagnose_data.py`

清除数据： `clear.py`

1. `search_documentation` -语义向量搜索

2. `hybrid_search` -矢量+图形上下文

3. `get_page` -检索特定页面

4. `get_document_info` -目录与统计

1. `https://graphrag.db/schema/neo4j`

2. `https://graphrag.db/collection/qdrant`

3. `https://graphrag.db/documents/list`