Unreal Engine Code Analyzer MCP Server

Unreal Engine 代码分析器 MCP 服务

一种模型上下文协议（MCP）服务，为 Unreal Engine 代码库提供强大的源代码分析能力。此工具使 Claude 和 Cline 等 AI 助手能够深入理解和分析 Unreal Engine 源代码。

功能

• 类分析：获取 C++ 类的详细信息，包括方法、属性和继承关系
• 层级映射：可视化并理解类的继承层级
• 代码搜索：搜索代码并获取具有上下文的结果
• 引用查找：定位类、函数或变量的所有引用
• 子系统分析：分析 Unreal Engine 的主要子系统，例如渲染、物理等
• 游戏类型知识：内置游戏类型、功能和实现模式的知识库
• 模式检测与学习：识别常见的 Unreal Engine 模式并提供学习资源
• 自定义代码库支持：分析你自己的 Unreal Engine 项目代码库

快速开始

安装

1. 克隆此仓库：

git clone https://github.com/ayeletstudioindia/unreal-analyzer-mcp
cd unreal-analyzer-mcp

2. 安装依赖项：

npm install

3. 构建项目：

npm run build

配置

用于 Claude Desktop App

将以下内容添加到 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++ 应用程序或库

分析自定义游戏引擎的示例：

// Initialize with custom codebase
{
  "name": "set_custom_codebase",
  "arguments": {
    "path": "/path/to/game-engine"
  }
}

// Analyze engine's renderer class
{
  "name": "analyze_class",
  "arguments": {
    "className": "Renderer"
  }
}

// Find all shader-related code
{
  "name": "search_code",
  "arguments": {
    "query": "shader|glsl|hlsl",
    "filePattern": "*.{h,cpp,hpp}"
  }
}

// Get render system class hierarchy
{
  "name": "find_class_hierarchy",
  "arguments": {
    "className": "RenderSystem",
    "includeImplementedInterfaces": true
  }
}

分析 Qt 应用程序的示例：

// Initialize with Qt project
{
  "name": "set_custom_codebase",
  "arguments": {
    "path": "/path/to/qt-app"
  }
}

// Find widget class definitions
{
  "name": "search_code",
  "arguments": {
    "query": "class.*:.*public.*QWidget",
    "filePattern": "*.h"
  }
}

// Analyze main window class
{
  "name": "analyze_class",
  "arguments": {
    "className": "MainWindow"
  }
}

// Find signal/slot connections
{
  "name": "find_references",
  "arguments": {
    "identifier": "connect",
    "type": "function"
  }
}

可用工具

1. 类分析

// Get detailed information about the AActor class
{
  "name": "analyze_class",
  "arguments": {
    "className": "AActor"
  }
}

输出示例：

{
  "name": "AActor",
  "properties": [
    {
      "name": "RootComponent",
      "type": "USceneComponent*",
      "access": "protected"
    }
    // ... other properties
  ],
  "methods": [
    {
      "name": "BeginPlay",
      "returnType": "void",
      "access": "protected",
      "virtual": true
    }
    // ... other methods
  ]
}

2. 类层级分析

// Get the inheritance hierarchy for ACharacter
{
  "name": "find_class_hierarchy",
  "arguments": {
    "className": "ACharacter",
    "includeImplementedInterfaces": true
  }
}

输出示例：

{
  "class": "ACharacter",
  "inheritsFrom": "APawn",
  "interfaces": ["IMovementModeInterface"],
  "hierarchy": [
    "ACharacter",
    "APawn",
    "AActor",
    "UObject"
  ]
}

3. 引用查找

// Find all references to the BeginPlay function
{
  "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. 代码搜索

// Search for physics-related code
{
  "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 最佳实践：

模式检测

// Detect patterns in a file
{
  "name": "detect_patterns",
  "arguments": {
    "filePath": "Source/MyGame/MyActor.h"
  }
}

输出示例：

{
  "patterns": [
    {
      "pattern": "UPROPERTY Macro",
      "description": "Property declaration for Unreal reflection system",
      "location": "Source/MyGame/MyActor.h:15",
      "context": "UPROPERTY(EditAnywhere, BlueprintReadWrite)\nfloat Health;",
      "improvements": "Consider adding a Category specifier for better organization\nConsider adding Meta tags for validation",
      "documentation": "https://docs.unrealengine.com/5.0/en-US/unreal-engine-uproperty-specifier-reference/",
      "bestPractices": "Use appropriate specifiers (EditAnywhere, BlueprintReadWrite)\nConsider replication needs (Replicated, ReplicatedUsing)\nGroup related properties with categories",
      "examples": "UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = \"Combat\")\nfloat Health;\nUPROPERTY(Replicated, Meta = (ClampMin = \"0.0\"))\nfloat Speed;"
    }
  ]
}

最佳实践指南

// Get best practices for specific Unreal concepts
{
  "name": "get_best_practices",
  "arguments": {
    "concept": "UPROPERTY"  // or UFUNCTION, Components, Events, Replication, Blueprints
  }
}

输出示例：

{
  "description": "Property declaration for Unreal reflection system",
  "bestPractices": [
    "Use appropriate specifiers (EditAnywhere, BlueprintReadWrite)",
    "Consider replication needs (Replicated, ReplicatedUsing)",
    "Group related properties with categories",
    "Use Meta tags for validation and UI customization"
  ],
  "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：函数反射与 Blueprint 集成
• 组件：组件的创建与管理
• 事件：事件处理与委托
• 复制：网络复制设置
• Blueprints：Blueprint/C++ 交互模式

6. API 文档查询

// Search the API documentation
{
  "name": "query_api",
  "arguments": {
    "query": "Actor",
    "category": "Object",
    "module": "Core",
    "includeExamples": true,
    "maxResults": 10
  }
}

输出示例：

{
  "results": [
    {
      "class": "AActor",
      "description": "Base class for all actors in the game",
      "module": "Core",
      "category": "Object",
      "syntax": "class AActor : public UObject",
      "examples": [
        "// Create a new actor\nAActor* MyActor = GetWorld()->SpawnActor<AActor>();"
      ],
      "remarks": [
        "Actors are the base building blocks of the game",
        "Can be placed in levels or spawned dynamically"
      ],
      "documentation": "https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Core/AActor",
      "relevance": 100
    }
  ]
}

API 文档查询工具提供：

• 跨类文档全文搜索
• 按类别和模块筛选
• 代码示例和用法模式
• 根据相关性对结果排序
• 官方文档链接

7. 子系统分析

// Analyze the Physics subsystem
{
  "name": "analyze_subsystem",
  "arguments": {
    "subsystem": "Physics"
  }
}

示例输出：

{
  "name": "Physics",
  "coreClasses": [
    "UPhysicsEngine",
    "FPhysScene",
    "UBodySetup"
  ],
  "keyFeatures": [
    "PhysX integration",
    "Collision detection",
    "Physical materials"
  ],
  "commonUseCases": [
    "Character movement",
    "Vehicle simulation",
    "Destructible environments"
  ]
}

API 文档

分析器现在具备全面的 API 文档功能：

1. 自动生成文档

   • 从源代码注释中提取文档
   • 分析类结构和关系
   • 按类型和模块对类进行分类
   • 生成语法示例和用法模式

2. 智能搜索

   • 对所有文档进行全文搜索
   • 根据相关性对结果排序
   • 按类别和模块筛选
   • 包含代码示例

3. 文档类别

   • Object：基础对象类（UObject 派生类）
   • Actor：Actor 类（AActor 派生类）
   • Structure：数据结构和类型
   • Component：组件类
   • Miscellaneous：其他类和实用工具

4. 模块组织

   • Core：核心引擎功能
   • RenderCore：渲染系统
   • PhysicsCore：物理引擎
   • 以及其他引擎模块

5. 与现有工具集成

   • 链接到类分析以获取详细信息
   • 连接到模式检测以了解最佳实践
   • 参考 Unreal Engine 官方文档
   • 提供学习资源和示例

最佳实践

1. 使用分析工具前，务必设置 Unreal Engine 路径或自定义代码库路径
2. 分析时使用具体的类名（例如，使用“MyClass”而非仅使用“Class”）
3. 在 search_code 中利用文件模式参数缩小搜索结果范围
4. 分析类层次结构时，包含已实现的接口，以便全面了解
5. 深入分析特定类之前，先使用子系统分析工具获取高层概览（仅适用于 Unreal Engine）

错误处理

出现以下情况时，分析器会抛出明确的错误消息：

• 未设置代码库路径（Unreal Engine 或自定义路径）
• 提供的路径不存在或无法访问
• 在代码库中找不到类或符号
• 提供了无效的文件模式
• 搜索查询或 C++ 代码中存在语法错误
• 对源文件的访问受到限制
• C++ 文件的 Tree-sitter 解析失败

性能注意事项

• 分析大型代码库可能需要更长时间
• 复杂的类层次结构可能需要更多处理时间
• 宽泛的搜索模式可能会产生大量匹配项
• 考虑使用更具体的查询以加快结果返回速度

测试

该项目针对所有主要组件提供了全面的测试覆盖：

测试覆盖范围

• 分析器测试：针对 UnrealCodeAnalyzer 类核心功能的测试

  • 初始化和路径验证
  • 类分析和解析
  • 查找引用
  • 代码搜索
  • 子系统分析
  • 缓存管理

• 游戏类型测试：验证游戏类型知识库

  • 数据结构验证
  • 特定类型的功能验证
  • 组件命名约定
  • 数据完整性检查

• MCP 服务测试：测试 MCP 服务实现

  • 服务初始化
  • 工具注册和处理
  • 请求／响应验证
  • 错误处理
  • 特定工具功能测试

运行测试

运行所有测试：

npm test

以监视模式运行测试（在开发过程中很有用）：

npm run test:watch

编写测试

贡献新功能时，请确保：

1. 所有新功能都有相应的测试覆盖
2. 测试放在 src/__tests__ 目录中
3. 以适当的方式模拟外部依赖
4. 遵循现有测试模式以保持一致性

贡献

欢迎贡献！欢迎提交拉取请求，改进以下方面：

• 源代码解析能力
• 新的分析功能
• 性能优化
• 文档改进
• 测试覆盖率

提交 PR 前：

1. 确保所有测试通过（npm test）
2. 为新功能添加测试
3. 根据需要更新文档