# 虚幻引擎知识图谱 MCP 服务器
[English](README_EN.md) | 中文
这个项目提供虚幻引擎官方文档的 MCP（Model Context Protocol）服务器，支持**基于Neo4j图数据库的概念关系搜索**，帮助开发者发现概念间的学习路径和依赖关系。
## 项目背景
在学习虚幻引擎开发过程中，开发者经常需要理解各种概念之间的关系，比如：
- 蓝图系统与C++代码的关系
- 材质编辑器与节点图编程的关系
- Nanite虚拟几何体与高多边形模型的关系
传统的文档搜索只能找到单个概念的信息，无法揭示概念间的学习路径和依赖关系。本项目通过构建知识图谱，让AI能够理解概念间的关联，提供更智能的学习指导。
## 解决方案
本项目提供了一个基于Neo4j图数据库的MCP服务器，专门用于虚幻引擎概念关系的智能搜索和发现。通过DeepSeek v3模型提取文档中的概念关系，构建完整的知识图谱。
## 功能特性
- 🔗 **概念关系搜索**: 发现任意概念的相关概念和学习路径
- 🧠 **智能概念发现**: 基于图数据库的深度关系挖掘
- 🔍 **概念名称搜索**: 模糊搜索概念名称，支持中英文双语查询
- 📊 **关系统计信息**: 获取概念的关系数量统计，按重要性排序
## 在 MCP Host 中使用
### Cursor 配置
在项目根目录创建或编辑 `.cursor/mcp.json` 配置文件：
```json
{
"mcpServers": {
"unreal-engine-knowledge-graph-mcp": {
"command": "npx",
"args": [
"-y",
"unreal-engine-knowledge-graph-mcp"
],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"NEO4J_PASSWORD": "password123"
}
}
}
}
```
### VSCode 配置
在项目根目录创建或编辑 `.vscode/mcp.json` 配置文件：
```json
{
"servers": {
"unreal-engine-knowledge-graph-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"unreal-engine-knowledge-graph-mcp"
],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"NEO4J_PASSWORD": "password123"
}
}
}
}
```
### 环境变量说明
| 环境变量 | 含义 | 默认值 |
|---------|------|--------|
| `NEO4J_URI` | Neo4j数据库连接地址 | `bolt://localhost:7687` |
| `NEO4J_USER` | Neo4j用户名 | `neo4j` |
| `NEO4J_PASSWORD` | Neo4j密码 | `password123` |
| `DEEPSEEK_API_KEY` | DeepSeek API密钥 | 无 |
## MCP工具功能
### search_concept_relations
搜索指定概念的相关概念和关系，支持中英文双语查询。
**使用场景:**
- 🎯 **概念学习扩展**: "我想学习蓝图系统，相关的概念还有哪些？"
- 🔍 **技术关联探索**: "虚幻引擎包含哪些核心功能模块？"
- 🧭 **学习路径规划**: "从材质编辑器出发，我还需要了解什么？"
**提示词示例:**
```
帮我搜索"蓝图系统"和"Blueprint System"的相关概念，我想了解它与其他功能的关系
查找"虚幻引擎"和"Unreal Engine"包含哪些核心功能
搜索"材质编辑器"和"Material Editor"相关的学习内容
```
**参数:**
- `concept` (必需): 要查询的概念名称（中英文双语）
- `cn` (必需): 中文概念名称
- `en` (必需): 英文概念名称
- `limit` (可选): 返回的最大关系数量，默认20
**返回数据格式:**
```json
{
"searchTerms": {
"cn": "虚幻引擎",
"en": "Unreal Engine"
},
"concept": "虚幻引擎 / Unreal Engine",
"found": true,
"totalRelations": 12,
"relatedConcepts": [
{
"concept": "蓝图系统",
"predicate": "包含",
"context": "虚幻引擎的可视化脚本编程系统",
"direction": "outgoing"
}
],
"limit": 20
}
```
### search_concepts
模糊搜索概念名称，支持中英文双语查询。
**使用场景:**
- 🔍 **快速查找概念**: "我记得有个关于'粒子'的功能，叫什么名字来着？"
- 📝 **概念名称确认**: "虚幻引擎中2D相关的功能都有哪些？"
- 🎯 **关键词探索**: "搜索包含'编辑器'的所有概念"
**提示词示例:**
```
搜索包含"粒子"和"Particle"的所有概念
查找与"2D"相关的功能
搜索"编辑器"和"Editor"相关的工具
```
**参数:**
- `searchTerm` (必需): 搜索关键词（中英文双语）
- `cn` (必需): 中文搜索关键词
- `en` (必需): 英文搜索关键词
- `limit` (可选): 返回的最大概念数量，默认10
**返回数据格式:**
```json
{
"searchTerms": {
"cn": "蓝图",
"en": "Blueprint"
},
"concepts": ["蓝图系统", "蓝图编辑器", "Blueprint System", "Blueprint Editor"],
"count": 4,
"limit": 10
}
```
### get_all_concepts
获取所有可用概念列表及其关系统计信息（按关系数量排序，优先显示核心概念）。
**使用场景:**
- 📋 **核心概念优先浏览**: "虚幻引擎知识图谱中最重要的概念有哪些？"
- 🎯 **学习计划制定**: "我想按重要性顺序学习，哪些是核心概念？"
- 📊 **概念关系分析**: "这些概念分别有多少关联，哪些最核心？"
**提示词示例:**
```
显示最重要的虚幻引擎概念，按关系数量排序
列出前50个核心概念，我想了解哪些最重要
获取概念列表及其关系统计，帮我制定学习计划
```
**参数:**
- `limit` (可选): 返回的最大概念数量，默认100
**返回数据格式:**
```json
{
"concepts": [
{
"concept": "蓝图系统",
"relationCount": 25,
"incomingCount": 12,
"outgoingCount": 13
},
{
"concept": "虚幻引擎",
"relationCount": 20,
"incomingCount": 8,
"outgoingCount": 12
}
],
"count": 2,
"limit": 100,
"note": "概念按关系数量从大到小排序，包含入度、出度和总关系数统计"
}
```
## 系统架构
### 核心组件
1. **文档处理**: 读取Markdown文档，使用DeepSeek v3提取概念关系
2. **知识图谱**: 基于Neo4j存储概念和关系数据
3. **MCP服务**: 提供标准化的概念关系查询接口
### 数据流程
```
Markdown文档 → DeepSeek v3分析 → 概念关系提取 → Neo4j图数据库 → MCP工具查询
```
## 开发测试
### 环境要求
- Node.js >= 18.0.0
- Docker (用于运行Neo4j)
- DeepSeek API密钥
### 安装步骤
1. **克隆项目**
```bash
git clone https://github.com/your-username/unreal-engine-knowledge-graph-mcp.git
cd unreal-engine-knowledge-graph-mcp
```
2. **安装依赖**
```bash
npm install
```
3. **配置环境变量**
```bash
# 复制环境变量模板
cp .env.example .env
# 编辑.env文件，添加DeepSeek API密钥
DEEPSEEK_API_KEY=your_deepseek_api_key_here
```
4. **启动Neo4j数据库**
```bash
# 启动Docker容器
docker-compose up -d
# 等待数据库启动完成
npm run test-connection
```
5. **构建项目**
```bash
npm run build
```
6. **提取概念关系（测试模式）**
```bash
# 测试模式：只处理一个文档文件
npm run extract-triplets:test-mode
```
7. **导入数据到Neo4j**
```bash
npm run import-to-neo4j
```
## 知识三元组数据结构
系统使用标准的知识图谱三元组结构存储概念关系：
```json
{
"filename": "文档名称",
"sourceFile": "源文件路径",
"triples": [
{
"subject": "主体概念",
"predicate": "关系谓词",
"object": "客体概念",
"context": "上下文说明",
"direction": "bidirectional"
}
],
"timestamp": "创建时间戳"
}
```
**字段说明：**
- `subject`: 主体概念名称（知识三元组的主语）
- `predicate`: 关系谓词（如：包含、支持、依赖、关联等）
- `object`: 客体概念名称（知识三元组的宾语）
- `context`: 关系的上下文说明，帮助理解关系的具体含义
- `direction`: 关系方向性
- `"unidirectional"`: 单向关系（主体→客体，但客体不一定→主体）
- `"bidirectional"`: 双向关系（主体↔客体，相互关联）
- `confidence`: 置信度（0.0-1.0），表示关系提取的准确性和可靠性
- `0.9-1.0`: 明确的技术关系，文档中有直接、清晰的说明
- `0.7-0.9`: 较为明确的关系，基于上下文推断但证据充分
- `0.5-0.7`: 中等置信度，关系存在但需要一定推理
- `0.3-0.5`: 较弱的关系，主要基于语义相似性
- `0.1-0.3`: 非常弱的关系，仅基于概念共现
## 开发指南
### 项目结构
```
├── scripts/ # 脚本文件
│ ├── extract-triplets.ts # 知识三元组提取
│ ├── import-to-neo4j.ts # 数据导入Neo4j
│ └── test-connection.ts # 数据库连接测试
├── bin/ # 源代码
│ ├── index.ts # MCP服务器实现
│ └── neo4j-search.ts # Neo4j搜索引擎
├── sources/ # 数据文件
│ ├── docs/ # Markdown文档
│ └── triplets/ # 知识三元组JSON文件
├── tests/ # 测试文件
│ └── mcp-client.test.ts # MCP客户端测试
├── docker-compose.yml # Neo4j Docker配置
└── package.json # 项目配置
```
### 可用脚本
```bash
# 构建项目
npm run build
# 测试数据库连接
npm run test-connection
# 生成演示数据
npm run extract-triplets:test-mode
# 提取知识三元组（需要DeepSeek API）
npm run extract-triplets
# 导入数据到Neo4j
npm run import-to-neo4j
# 清空数据库并重新导入
npm run import-to-neo4j -- --clear
# 运行测试
npm test
```
### 添加新文档
1. 将Markdown文档放入 `sources/docs/` 目录
2. 运行概念关系提取：`npm run extract-triplets`
3. 导入到Neo4j：`npm run import-to-neo4j`
### 自定义知识三元组
你可以手动创建知识三元组JSON文件：
```json
{
"filename": "custom-triples",
"sourceFile": "custom/triples.md",
"triples": [
{
"subject": "自定义概念A",
"predicate": "关联",
"object": "自定义概念B",
"context": "这是一个自定义的知识三元组",
"direction": "bidirectional"
}
],
"timestamp": "2025-01-12T10:30:15.387Z"
}
```
将文件保存到 `sources/triplets/` 目录，然后运行导入命令。
## 技术栈
### 核心技术
- **Node.js**: 运行环境
- **TypeScript**: 类型安全的开发语言
- **MCP SDK**: Model Context Protocol 实现
- **Neo4j**: 图数据库
- **Docker**: 容器化部署
### AI集成
- **DeepSeek v3**: 概念关系提取
- **OpenAI SDK**: API调用接口
### 开发工具
- **Vitest**: 单元测试框架
- **tsx**: TypeScript执行器
- **Zod**: 参数验证
## 故障排除
### Neo4j连接问题
```bash
# 检查Docker容器状态
docker-compose ps
# 查看Neo4j日志
docker-compose logs neo4j
# 重启Neo4j容器
docker-compose restart neo4j
```
### 测试连接
```bash
npm run test-connection
```
### 查看Neo4j浏览器界面
访问 http://localhost:7474
- 用户名: neo4j
- 密码: password123
## 许可证
MIT License
## 贡献
欢迎提交Issue和Pull Request！
