---
alwaysApply: true
---

# Unreal Project Analyzer - 项目概览

## 项目愿景

让 AI 能够完整追踪 Unreal 项目中任意一条引用链，从入口到实现，跨越 Blueprint ↔ C++ ↔ Asset 边界。

**核心场景**：分析 Lyra 等大型 Unreal 项目，追踪如 GAS Ability 从触发到执行的完整链路。

## 架构

```
AI Agent
    │ MCP Protocol
    ▼
MCP Server (Python/FastMCP)
    │ - C++ 源码分析 (tree-sitter)
    │ - 工具路由
    │ HTTP
    ▼
Unreal Plugin (Editor 内运行)
    ├─ C++ HTTP Server (:8080)
    │   - Blueprint 内省 API
    │   - Asset 引用查询 API
    └─ Python Bridge (自动拉起)
        - Unreal Python 补充 API
```

## 目录结构

```
unreal-project-analyzer/           # 主项目目录
├── Mcp/src/unreal_analyzer/       # MCP Server (Python)
│   ├── server.py               # 入口
│   ├── tools/                  # MCP 工具定义
│   ├── cpp_analyzer/           # C++ 源码分析 (tree-sitter)
│   └── ue_client/              # UE 插件 HTTP 客户端
│
├── Source/                     # Unreal C++ 插件代码
└── Content/Python/             # Python Bridge
│
└── Mcp/tests/                  # 测试

docs/                           # 项目文档
reference/                      # 参考项目 (不修改)
```

## 关键文件

- [PROJECT_VISION.md](mdc:docs/PROJECT_VISION.md) - 详细项目愿景和技术规划
- [server.py](mdc:Mcp/src/unreal_analyzer/server.py) - MCP Server 入口
- [UnrealProjectAnalyzer.cpp](mdc:Source/UnrealProjectAnalyzer/Private/UnrealProjectAnalyzer.cpp) - Unreal 插件入口

## 技术栈

| 组件 | 技术选型 |
|------|----------|
| Python 包管理 | uv |
| MCP 框架 | FastMCP |
| C++ 解析 | tree-sitter + tree-sitter-cpp |
| UE 通信 | HTTP (自研插件) |
| UE 版本 | 5.3+ |

## 当前版本：v0.3.1

**8 个工具**（4 核心 + 4 特殊）：

| 核心工具 | 特殊工具 |
|----------|----------|
| `search` | `get_blueprint_graph` |
| `get_hierarchy` | `detect_ue_patterns` |
| `get_references` | `trace_reference_chain` |
| `get_details` | `find_cpp_class_usage` |

详见 [mcp-tools-design.mdc](mdc:.cursor/rules/mcp-tools-design.mdc)