<!-- 由 Ayelet Technology Private Limited 创建 -->

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://glama.ai/mcp/servers/z36022whws/badge" alt="Unreal Engine Code Analyzer Server MCP server" /></a>

功能

• 类分析: 获取关于 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 桌面应用

将以下内容添加到您的 Claude 桌面配置文件 (%APPDATA%\Claude\claude_desktop_config.json，在 Windows 上):

{
  "mcpServers": {
    "unreal-analyzer": {
      "command": "node",
      "args": ["path/to/unreal-analyzer/build/index.js"],
      "env": {}
    }
  }
}

对于 Cline

将以下内容添加到您的 Cline MCP 设置文件 (%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json，在 Windows 上):

{
  "mcpServers": {
    "unreal-analyzer": {
      "command": "node",
      "args": ["path/to/unreal-analyzer/build/index.js"],
      "env": {}
    }
  }
}

技术细节

该分析器使用以下技术构建：

• TypeScript 用于类型安全的代码
• Tree-sitter 用于强大的 C++ 解析
• 模型上下文协议 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"
  }
}

// 查找 widget 类定义
{
  "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 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;"
    }
  ]
}

最佳实践指南

// 获取特定 Unreal 概念的最佳实践
{
  "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：函数反射和蓝图集成
• Components：组件创建和管理
• Events：事件处理和委托
• Replication：网络复制设置
• Blueprints：蓝图/C++ 交互模式

6. API 文档查询

// 搜索 API 文档
{
  "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. 子系统分析

// 分析物理子系统
{
  "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++ 代码中的语法错误
• 限制对源文件的访问
• Tree-sitter 解析 C++ 文件失败

性能考虑

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

测试

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

测试覆盖

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

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

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

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

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

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

运行测试

运行所有测试：

npm test

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

npm run test:watch

编写测试

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

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

贡献

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

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

在提交 PR 之前：

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