Unreal Engine 代码分析器 MCP 服务器

这是一个提供强大源代码分析功能的 Model Context Protocol (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

1. 安装依赖项：

npm install

1. 构建项目：

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++ 应用程序或库

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

// 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. 模式检测与最佳实践

分析器提供了两个强大的工具，用于理解和遵循虚幻引擎的最佳实践：

模式检测

// 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/"
}

最佳实践指南涵盖了虚幻引擎的关键概念：

• UPROPERTY：属性反射和暴露
• UFUNCTION：函数反射和蓝图集成
• 组件：组件创建和管理
• 事件：事件处理和委托
• 复制：网络复制设置
• 蓝图：蓝图/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. 文档类别

   • 对象：基础对象类（UObject 的派生类）
   • Actor：Actor 类（AActor 的派生类）
   • 结构体：数据结构和类型
   • 组件：组件类
   • 杂项：其他类和实用工具

4. 模块组织

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

5. 与现有工具集成

   • 与类分析链接以获取详细信息
   • 与模式检测连接以遵循最佳实践
   • 引用虚幻引擎官方文档
   • 提供学习资源和示例

最佳实践

1. 在使用分析工具之前，始终设置虚幻引擎路径或自定义代码库路径
2. 分析时使用具体的类名（例如，“MyClass”而不是“Class”）
3. 在 search_code 中利用文件模式参数来缩小结果范围
4. 在分析类层次结构时包含实现的接口，以获得完整的理解
5. 使用子系统分析工具在深入特定类之前获取高级概述（仅限虚幻引擎）

错误处理

当出现以下情况时，分析器将抛出清晰的错误消息：

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

性能考虑

• 大型代码库可能需要更长的时间来分析
• 复杂的类层次结构可能需要更多的处理时间
• 宽泛的搜索模式可能导致大量匹配
• 考虑使用更具体的查询以获得更快的结果

测试

项目包括对所有主要组件的全面测试覆盖：

测试覆盖范围

• Analyzer Tests：针对 UnrealCodeAnalyzer 类的核心功能测试

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

• Game Genres Tests：游戏类型知识库的验证

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

• MCP Server Tests：MCP 服务器实现的测试

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

运行测试

运行所有测试：

npm test

在监视模式下运行测试（开发期间有用）：

npm run test:watch

编写测试

在贡献新功能时，请确保：

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

贡献

欢迎贡献！请随时提交带有以下改进的拉取请求：

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

在提交 PR 之前：

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