项目介绍
Unreal Engine 代码分析器 MCP 服务器
这是一个基于模型上下文协议（MCP）的服务器，提供强大的源代码分析功能，专门针对 Unreal Engine 代码库。此工具使像 Claude 和 Cline 这样的AI助手能够深入理解并分析 Unreal Engine 源代码。
<a href="https://glama.ai/mcp/servers/z36022whws"><img width="380" height="200" src="https://gips1.baidu.com/it/u=1585994291,3245614023&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Unreal Engine 代码分析器 MCP 服务器" /></a>
功能
- 类分析：获取关于 C++ 类的详细信息，包括方法、属性和继承关系
- 层次映射：可视化并理解类的继承层次结构
- 代码搜索：根据上下文进行代码搜索
- 引用查找：定位所有对类、函数或变量的引用
- 子系统分析：分析 Unreal Engine 的主要子系统，如渲染、物理等
- 游戏类型知识：内置的游戏类型、特性和实现模式的知识库
- 模式检测与学习：识别常见的 Unreal Engine 模式，并提供学习资源
- 自定义代码库支持：分析您自己的 Unreal Engine 项目代码库
快速开始
安装
- 克隆此仓库：
git clone https://github.com/ayeletstudioindia/unreal-analyzer-mcp
cd unreal-analyzer-mcp
- 安装依赖项：
npm install
- 构建项目：
npm run build
配置
对于 Claude 桌面应用
在您的 Claude 桌面配置文件中添加以下内容（Windows 系统路径为 %APPDATA%\Claude\claude_desktop_config.json）：
{
"mcpServers": {
"unreal-analyzer": {
"command": "node",
"args": ["path/to/unreal-analyzer/build/index.js"],
"env": {}
}
}
}
对于 Cline
在您的 Cline MCP 设置文件中添加以下内容（Windows 系统路径为 %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json）：
{
"mcpServers": {
"unreal-analyzer": {
"command": "node",
"args": ["path/to/unreal-analyzer/build/index.js"],
"env": {}
}
}
}
技术细节
分析器使用以下构建：
- 使用 TypeScript 实现类型安全代码
- 使用 Tree-sitter 实现健壮的 C++ 解析
- 使用 Model Context Protocol SDK 实现 AI 助手集成
- 使用 Glob 进行文件模式匹配
关键依赖项：
- @modelcontextprotocol/create-server: ^0.1.0
- tree-sitter: ^0.20.1
- tree-sitter-cpp: ^0.20.0
- glob: ^8.1.0
使用
在使用任何分析工具之前，必须先设置 Unreal Engine 源代码路径或自定义代码库路径：
分析设置
对于 Unreal Engine 源代码
{
"name": "set_unreal_path",
"arguments": {
"path": "/path/to/UnrealEngine/Source"
}
}
对于自定义 C++ 代码库
{
"name": "set_custom_codebase",
"arguments": {
"path": "/path/to/your/codebase"
}
}
自定义代码库功能允许您分析任何 C++ 项目。例如：
- 游戏引擎（Unity、Godot、自定义引擎）
- 图形库（OpenGL、Vulkan、DirectX）
- 框架（Qt、Boost、SFML）
- 任何 C++ 应用程序或库
分析自定义游戏引擎示例：
// 使用自定义代码库初始化
{
"name": "set_custom_codebase",
"arguments": {
"path": "/path/to/game-engine"
}
}
// 分析引擎的渲染器类
{
"name": "analyze_class",
"arguments": {
"className": "Renderer"
}
}
// 查找所有与着色器相关的代码
{
"name": "search_code",
"arguments": {
"query": "shader|glsl|hlsl",
"filePattern": "*.{h,cpp,hpp}"
}
}
// 获取渲染系统类层次结构
{
"name": "find_class_hierarchy",
"arguments": {
"className": "RenderSystem",
"includeImplementedInterfaces": true
}
}
分析 Qt 应用程序示例：
// 使用 Qt 项目初始化
{
"name": "set_custom_codebase",
"arguments": {
"path": "/path/to/qt-app"
}
}
// 查找小部件类定义
{
"name": "search_code",
"arguments": {
"query": "class.*:.*public.*QWidget",
"filePattern": "*.h"
}
}
// 分析主窗口类
{
"name": "analyze_class",
"arguments": {
"className": "MainWindow"
}
}
// 查找信号/槽连接
{
"name": "find_references",
"arguments": {
"identifier": "connect",
"type": "function"
}
}
可用工具
1. 类分析
// 获取关于 AActor 类的详细信息
{
"name": "analyze_class",
"arguments": {
"className": "AActor"
}
}
示例输出：
{
"name": "AActor",
"properties": [
{
"name": "RootComponent",
"type": "USceneComponent*",
"access": "protected"
}
// ... 其他属性
],
"methods": [
{
"name": "BeginPlay",
"returnType": "void",
"access": "protected",
"virtual": true
}
// ... 其他方法
]
}
2. 类层次分析
// 获取 ACharacter 的继承层次结构
{
"name": "find_class_hierarchy",
"arguments": {
"className": "ACharacter",
"includeImplementedInterfaces": true
}
}
示例输出：
{
"class": "ACharacter",
"inheritsFrom": "APawn",
"interfaces": ["IMovementModeInterface"],
"hierarchy": [
"ACharacter",
"APawn",
"AActor",
"UObject"
]
}
3. 引用查找
// 查找所有对 BeginPlay 函数的引用
{
"name": "find_references",
"arguments": {
"identifier": "BeginPlay",
"type": "function"
}
}
示例输出：
{
"references": [
{
"file": "Actor.cpp",
"line": 245,
"context": "void AActor::BeginPlay() { ... }"
},
{
"file": "Character.cpp",
"line": 178,
"context": "Super::BeginPlay();"
}
]
}
4. 代码搜索
// 搜索与物理相关的代码
{
"name": "search_code",
"arguments": {
"query": "PhysicsHandle",
"filePattern": "*.h",
"includeComments": true
}
}
示例输出：
{
"matches": [
{
"file": "PhysicsEngine/PhysicsHandleComponent.h",
"line": 15,
"context": "class UPhysicsHandleComponent : public UActorComponent",
"snippet": "// Component used for grabbing and moving physics objects"
}
]
}
5. 模式检测与最佳实践
分析器提供了两个强大的工具来理解和遵循 Unreal Engine 最佳实践：
模式检测
// 在文件中检测模式
{
"name": "detect_patterns",
"arguments": {
"filePath": "Source/MyGame/MyActor.h"
}
}
示例输出：
{
"patterns": [
{
"pattern": "UPROPERTY 宏",
"description": "用于 Unreal 反射系统的属性声明",
"location": "Source/MyGame/MyActor.h:15",
"context": "UPROPERTY(EditAnywhere, BlueprintReadWrite)\nfloat Health;",
"improvements": "考虑添加一个 Category 标签以更好地组织\n考虑添加 Meta 标签进行验证",
"documentation": "https://docs.unrealengine.com/5.0/en-US/unreal-engine-uproperty-specifier-reference/",
"bestPractices": "使用适当的标签 (EditAnywhere, BlueprintReadWrite)\n考虑复制需求 (Replicated, ReplicatedUsing)\n使用类别分组相关属性",
"examples": "UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = \"Combat\")\nfloat Health;\nUPROPERTY(Replicated, Meta = (ClampMin = \"0.0\"))\nfloat Speed;"
}
]
}
最佳实践指南
// 获取特定 Unreal 概念的最佳实践
{
"name": "get_best_practices",
"arguments": {
"concept": "UPROPERTY" // 或 UFUNCTION, Components, Events, Replication, Blueprints
}
}
示例输出：
{
"description": "用于 Unreal 反射系统的属性声明",
"bestPractices": [
"使用适当的标签 (EditAnywhere, BlueprintReadWrite)",
"考虑复制需求 (Replicated, ReplicatedUsing)",
"使用类别分组相关属性",
"使用 Meta 标签进行验证和 UI 自定义"
],
"examples": [
"UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = \"Combat\")\nfloat Health;",
"UPROPERTY(Replicated, Meta = (ClampMin = \"0.0\"))\nfloat Speed;"
],
"documentation": "https://docs.unrealengine.com/5.0/en-US/unreal-engine-uproperty-specifier-reference/"
}
最佳实践指南涵盖了关键的 Unreal Engine 概念：
- UPROPERTY：属性反射和暴露
- UFUNCTION：函数反射和蓝图集成
- 组件：组件创建和管理
- 事件：事件处理和委托
- 复制：网络复制设置
- 蓝图：蓝图/C++ 交互模式
6. API 文档查询
// 查询 API 文档
{
"name": "query_api",
"arguments": {
"query": "Actor",
"category": "Object",
"module": "Core",
"includeExamples": true,
"maxResults": 10
}
}
示例输出：
{
"results": [
{
"class": "AActor",
"description": "游戏中所有角色的基础类",
"module": "Core",
"category": "Object",
"syntax": "class AActor : public UObject",
"examples": [
"// 创建一个新的角色\nAActor* MyActor = GetWorld()->SpawnActor<AActor>();"
],
"remarks": [
"角色是游戏的基本构建块",
"可以在关卡中放置或动态生成"
],
"documentation": "https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Core/AActor",
"relevance": 100
}
]
}
API 文档查询工具提供：
- 跨越类文档的全文搜索
- 按类别和模块过滤
- 包含代码示例和使用模式
- 基于相关性的结果排序
- 链接到官方文档
7. 子系统分析
// 分析物理子系统
{
"name": "analyze_subsystem",
"arguments": {
"subsystem": "Physics"
}
}
示例输出：
{
"name": "Physics",
"coreClasses": [
"UPhysicsEngine",
"FPhysScene",
"UBodySetup"
],
"keyFeatures": [
"PhysX 集成",
"碰撞检测",
"物理材质"
],
"commonUseCases": [
"角色移动",
"车辆模拟",
"可破坏环境"
]
}
API 文档
分析器现在包括全面的 API 文档功能：
-
自动文档生成
- 从源代码注释中提取文档
- 分析类结构和关系
- 按类型和模块分类类
- 生成语法示例和使用模式
-
智能搜索
- 跨越所有文档的全文搜索
- 基于相关性的结果排名
- 按类别和模块过滤
- 包含代码示例
-
文档分类
- 对象：基础对象类（UObject 衍生类）
- 角色：角色类（AActor 衍生类）
- 结构：数据结构和类型
- 组件：组件类
- 杂项：其他类和实用工具
-
模块组织
- 核心：核心引擎功能
- 渲染核心：渲染系统
- 物理核心：物理引擎
- 其他引擎模块
-
与现有工具的集成
- 与类分析链接以获取详细信息
- 连接到模式检测以获取最佳实践
- 引用官方 Unreal Engine 文档
- 提供学习资源和示例
最佳实践
- 在使用分析工具前，始终设置 Unreal Engine 路径或自定义代码库路径
- 分析时使用具体的类名（例如，“MyClass”而不是“Class”）
- 使用
search_code中的文件模式参数缩小结果范围 - 分析类层次结构时包含实现的接口以获得完整的理解
- 使用子系统分析工具获取高层次概述，然后再深入具体类（仅限 Unreal Engine）
错误处理
当出现以下情况时，分析器会抛出清晰的错误消息：
- 未设置代码库路径（Unreal Engine 或自定义）
- 提供的路径不存在或无法访问
- 在代码库中找不到类或符号
- 提供了无效的文件模式
- 搜索查询或 C++ 代码中的语法错误
- 访问源文件受限
- C++ 文件的 Tree-sitter 解析失败
性能考虑
- 大型代码库可能需要更长时间来分析
- 复杂的类层次结构可能需要更多的处理时间
- 广泛的搜索模式可能会导致许多匹配项
- 考虑使用更具体的查询以加快结果
测试
该项目包括所有主要组件的全面测试覆盖：
测试覆盖
-
分析器测试：针对 UnrealCodeAnalyzer 类的核心功能测试
- 初始化和路径验证
- 类分析和解析
- 引用查找
- 代码搜索
- 子系统分析
- 缓存管理
-
游戏类型测试：验证游戏类型知识库
- 数据结构验证
- 特定游戏类型的特性验证
- 组件命名约定
- 数据完整性检查
-
MCP 服务器测试：测试 MCP 服务器实现
- 服务器初始化
- 工具注册和处理
- 请求/响应验证
- 错误处理
- 工具特定功能测试
运行测试
运行所有测试：
npm test
在开发期间运行监视模式下的测试（非常有用）：
npm run test:watch
编写测试
在贡献新功能时，请确保：
- 所有新功能都有相应的测试覆盖
- 测试组织在
src/__tests__目录下 - 合适地模拟外部依赖项
- 遵循现有的测试模式以保持一致性
贡献
欢迎贡献！请随时提交改进的拉取请求：
- 源代码解析能力
- 新的分析功能
- 性能优化
- 文档改进
- 测试覆盖
在提交 PR 之前：
- 确保所有测试通过 (
npm test) - 为新功能添加测试
- 如有必要，更新文档