Skip to content
Back to search

unreal-analyzer-mcp

MCP server for Unreal Engine 5

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ayeletstudioindia--unreal-analyzer-mcp/badge.svg)](/listings/ayeletstudioindia--unreal-analyzer-mcp)

HTML

<a href="/listings/ayeletstudioindia--unreal-analyzer-mcp"><img src="/api/listings/ayeletstudioindia--unreal-analyzer-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Clone this repository:

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

2. Install dependencies:

npm install

3. Build the project:

npm run build

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 583 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/ayeletstudioindia-unreal-analyzer-mcp-badge.png)](https://mseep.ai/app/ayeletstudioindia-unreal-analyzer-mcp)
  2. <!--
  3. Created by Ayelet Technology Private Limited
  4. -->
  5. # Unreal Engine Code Analyzer MCP Server
  6. A Model Context Protocol (MCP) server that provides powerful source code analysis capabilities for Unreal Engine codebases. This tool enables AI assistants like Claude and Cline to deeply understand and analyze Unreal Engine source code.
  7. <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>
  8. ## Features
  9. - **Class Analysis**: Get detailed information about C++ classes including methods, properties, and inheritance
  10. - **Hierarchy Mapping**: Visualize and understand class inheritance hierarchies
  11. - **Code Search**: Search through code with context-aware results
  12. - **Reference Finding**: Locate all references to classes, functions, or variables
  13. - **Subsystem Analysis**: Analyze major Unreal Engine subsystems like Rendering, Physics, etc.
  14. - **Game Genre Knowledge**: Built-in knowledge base of game genres, features, and implementation patterns
  15. - **Pattern Detection & Learning**: Identifies common Unreal Engine patterns and provides learning resources
  16. - **Custom Codebase Support**: Analyze your own Unreal Engine project codebase
  17. ## Quick Start
  18. ## Installation
  19. 1. Clone this repository:
  20. ```bash
  21. git clone https://github.com/ayeletstudioindia/unreal-analyzer-mcp
  22. cd unreal-analyzer-mcp
  23. ```
  24. 2. Install dependencies:
  25. ```bash
  26. npm install
  27. ```
  28. 3. Build the project:
  29. ```bash
  30. npm run build
  31. ```
  32. ## Configuration
  33. ### For Claude Desktop App
  34. Add the following to your Claude desktop configuration file (`%APPDATA%\Claude\claude_desktop_config.json` on Windows):
  35. ```json
  36. {
  37. "mcpServers": {
  38. "unreal-analyzer": {
  39. "command": "node",
  40. "args": ["path/to/unreal-analyzer/build/index.js"],
  41. "env": {}
  42. }
  43. }
  44. }
  45. ```
  46. ### For Cline
  47. Add the following to your Cline MCP settings file (`%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json` on Windows):
  48. ```json
  49. {
  50. "mcpServers": {
  51. "unreal-analyzer": {
  52. "command": "node",
  53. "args": ["path/to/unreal-analyzer/build/index.js"],
  54. "env": {}
  55. }
  56. }
  57. }
  58. ```
  59. ## Technical Details
  60. The analyzer is built using:
  61. - TypeScript for type-safe code
  62. - Tree-sitter for robust C++ parsing
  63. - Model Context Protocol SDK for AI assistant integration
  64. - Glob for file pattern matching
  65. Key dependencies:
  66. - @modelcontextprotocol/create-server: ^0.1.0
  67. - tree-sitter: ^0.20.1
  68. - tree-sitter-cpp: ^0.20.0
  69. - glob: ^8.1.0
  70. ## Usage
  71. Before using any analysis tools, you must first set either the Unreal Engine source path or a custom codebase path:
  72. ### Setting Up Analysis
  73. #### For Unreal Engine Source Code
  74. ```typescript
  75. {
  76. "name": "set_unreal_path",
  77. "arguments": {
  78. "path": "/path/to/UnrealEngine/Source"
  79. }
  80. }
  81. ```
  82. #### For Custom C++ Codebases
  83. ```typescript
  84. {
  85. "name": "set_custom_codebase",
  86. "arguments": {
  87. "path": "/path/to/your/codebase"
  88. }
  89. }
  90. ```
  91. The custom codebase feature allows you to analyze any C++ project. For example:
  92. - Game engines (Unity, Godot, custom engines)
  93. - Graphics libraries (OpenGL, Vulkan, DirectX)
  94. - Frameworks (Qt, Boost, SFML)
  95. - Any C++ application or library
  96. Example analyzing a custom game engine:
  97. ```typescript
  98. // Initialize with custom codebase
  99. {
  100. "name": "set_custom_codebase",
  101. "arguments": {
  102. "path": "/path/to/game-engine"
  103. }
  104. }
  105. // Analyze engine's renderer class
  106. {
  107. "name": "analyze_class",
  108. "arguments": {
  109. "className": "Renderer"
  110. }
  111. }
  112. // Find all shader-related code
  113. {
  114. "name": "search_code",
  115. "arguments": {
  116. "query": "shader|glsl|hlsl",
  117. "filePattern": "*.{h,cpp,hpp}"
  118. }
  119. }
  120. // Get render system class hierarchy
  121. {
  122. "name": "find_class_hierarchy",
  123. "arguments": {
  124. "className": "RenderSystem",
  125. "includeImplementedInterfaces": true
  126. }
  127. }
  128. ```
  129. Example analyzing a Qt application:
  130. ```typescript
  131. // Initialize with Qt project
  132. {
  133. "name": "set_custom_codebase",
  134. "arguments": {
  135. "path": "/path/to/qt-app"
  136. }
  137. }
  138. // Find widget class definitions
  139. {
  140. "name": "search_code",
  141. "arguments": {
  142. "query": "class.*:.*public.*QWidget",
  143. "filePattern": "*.h"
  144. }
  145. }
  146. // Analyze main window class
  147. {
  148. "name": "analyze_class",
  149. "arguments": {
  150. "className": "MainWindow"
  151. }
  152. }
  153. // Find signal/slot connections
  154. {
  155. "name": "find_references",
  156. "arguments": {
  157. "identifier": "connect",
  158. "type": "function"
  159. }
  160. }
  161. ```
  162. ### Available Tools
  163. #### 1. Class Analysis
  164. ```typescript
  165. // Get detailed information about the AActor class
  166. {
  167. "name": "analyze_class",
  168. "arguments": {
  169. "className": "AActor"
  170. }
  171. }
  172. ```
  173. Example output:
  174. ```json
  175. {
  176. "name": "AActor",
  177. "properties": [
  178. {
  179. "name": "RootComponent",
  180. "type": "USceneComponent*",
  181. "access": "protected"
  182. }
  183. // ... other properties
  184. ],
  185. "methods": [
  186. {
  187. "name": "BeginPlay",
  188. "returnType": "void",
  189. "access": "protected",
  190. "virtual": true
  191. }
  192. // ... other methods
  193. ]
  194. }
  195. ```
  196. #### 2. Class Hierarchy Analysis
  197. ```typescript
  198. // Get the inheritance hierarchy for ACharacter
  199. {
  200. "name": "find_class_hierarchy",
  201. "arguments": {
  202. "className": "ACharacter",
  203. "includeImplementedInterfaces": true
  204. }
  205. }
  206. ```
  207. Example output:
  208. ```json
  209. {
  210. "class": "ACharacter",
  211. "inheritsFrom": "APawn",
  212. "interfaces": ["IMovementModeInterface"],
  213. "hierarchy": [
  214. "ACharacter",
  215. "APawn",
  216. "AActor",
  217. "UObject"
  218. ]
  219. }
  220. ```
  221. #### 3. Reference Finding
  222. ```typescript
  223. // Find all references to the BeginPlay function
  224. {
  225. "name": "find_references",
  226. "arguments": {
  227. "identifier": "BeginPlay",
  228. "type": "function"
  229. }
  230. }
  231. ```
  232. Example output:
  233. ```json
  234. {
  235. "references": [
  236. {
  237. "file": "Actor.cpp",
  238. "line": 245,
  239. "context": "void AActor::BeginPlay() { ... }"
  240. },
  241. {
  242. "file": "Character.cpp",
  243. "line": 178,
  244. "context": "Super::BeginPlay();"
  245. }
  246. ]
  247. }
  248. ```
  249. #### 4. Code Search
  250. ```typescript
  251. // Search for physics-related code
  252. {
  253. "name": "search_code",
  254. "arguments": {
  255. "query": "PhysicsHandle",
  256. "filePattern": "*.h",
  257. "includeComments": true
  258. }
  259. }
  260. ```
  261. Example output:
  262. ```json
  263. {
  264. "matches": [
  265. {
  266. "file": "PhysicsEngine/PhysicsHandleComponent.h",
  267. "line": 15,
  268. "context": "class UPhysicsHandleComponent : public UActorComponent",
  269. "snippet": "// Component used for grabbing and moving physics objects"
  270. }
  271. ]
  272. }
  273. ```
  274. #### 5. Pattern Detection & Best Practices
  275. The analyzer provides two powerful tools for understanding and following Unreal Engine best practices:
  276. ##### Pattern Detection
  277. ```typescript
  278. // Detect patterns in a file
  279. {
  280. "name": "detect_patterns",
  281. "arguments": {
  282. "filePath": "Source/MyGame/MyActor.h"
  283. }
  284. }
  285. ```
  286. Example output:
  287. ```json
  288. {
  289. "patterns": [
  290. {
  291. "pattern": "UPROPERTY Macro",
  292. "description": "Property declaration for Unreal reflection system",
  293. "location": "Source/MyGame/MyActor.h:15",
  294. "context": "UPROPERTY(EditAnywhere, BlueprintReadWrite)\nfloat Health;",
  295. "improvements": "Consider adding a Category specifier for better organization\nConsider adding Meta tags for validation",
  296. "documentation": "https://docs.unrealengine.com/5.0/en-US/unreal-engine-uproperty-specifier-reference/",
  297. "bestPractices": "Use appropriate specifiers (EditAnywhere, BlueprintReadWrite)\nConsider replication needs (Replicated, ReplicatedUsing)\nGroup related properties with categories",
  298. "examples": "UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = \"Combat\")\nfloat Health;\nUPROPERTY(Replicated, Meta = (ClampMin = \"0.0\"))\nfloat Speed;"
  299. }
  300. ]
  301. }
  302. ```
  303. ##### Best Practices Guide
  304. ```typescript
  305. // Get best practices for specific Unreal concepts
  306. {
  307. "name": "get_best_practices",
  308. "arguments": {
  309. "concept": "UPROPERTY" // or UFUNCTION, Components, Events, Replication, Blueprints
  310. }
  311. }
  312. ```
  313. Example output:
  314. ```json
  315. {
  316. "description": "Property declaration for Unreal reflection system",
  317. "bestPractices": [
  318. "Use appropriate specifiers (EditAnywhere, BlueprintReadWrite)",
  319. "Consider replication needs (Replicated, ReplicatedUsing)",
  320. "Group related properties with categories",
  321. "Use Meta tags for validation and UI customization"
  322. ],
  323. "examples": [
  324. "UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = \"Combat\")\nfloat Health;",
  325. "UPROPERTY(Replicated, Meta = (ClampMin = \"0.0\"))\nfloat Speed;"
  326. ],
  327. "documentation": "https://docs.unrealengine.com/5.0/en-US/unreal-engine-uproperty-specifier-reference/"
  328. }
  329. ```
  330. The best practices guide covers key Unreal Engine concepts:
  331. - UPROPERTY: Property reflection and exposure
  332. - UFUNCTION: Function reflection and Blueprint integration
  333. - Components: Component creation and management
  334. - Events: Event handling and delegation
  335. - Replication: Network replication setup
  336. - Blueprints: Blueprint/C++ interaction patterns
  337. #### 6. API Documentation Query
  338. ```typescript
  339. // Search the API documentation
  340. {
  341. "name": "query_api",
  342. "arguments": {
  343. "query": "Actor",
  344. "category": "Object",
  345. "module": "Core",
  346. "includeExamples": true,
  347. "maxResults": 10
  348. }
  349. }
  350. ```
  351. Example output:
  352. ```json
  353. {
  354. "results": [
  355. {
  356. "class": "AActor",
  357. "description": "Base class for all actors in the game",
  358. "module": "Core",
  359. "category": "Object",
  360. "syntax": "class AActor : public UObject",
  361. "examples": [
  362. "// Create a new actor\nAActor* MyActor = GetWorld()->SpawnActor<AActor>();"
  363. ],
  364. "remarks": [
  365. "Actors are the base building blocks of the game",
  366. "Can be placed in levels or spawned dynamically"
  367. ],
  368. "documentation": "https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Core/AActor",
  369. "relevance": 100
  370. }
  371. ]
  372. }
  373. ```
  374. The API documentation query tool provides:
  375. - Full-text search across class documentation
  376. - Filtering by category and module
  377. - Code examples and usage patterns
  378. - Relevance-based sorting of results
  379. - Links to official documentation
  380. #### 7. Subsystem Analysis
  381. ```typescript
  382. // Analyze the Physics subsystem
  383. {
  384. "name": "analyze_subsystem",
  385. "arguments": {
  386. "subsystem": "Physics"
  387. }
  388. }
  389. ```
  390. Example output:
  391. ```json
  392. {
  393. "name": "Physics",
  394. "coreClasses": [
  395. "UPhysicsEngine",
  396. "FPhysScene",
  397. "UBodySetup"
  398. ],
  399. "keyFeatures": [
  400. "PhysX integration",
  401. "Collision detection",
  402. "Physical materials"
  403. ],
  404. "commonUseCases": [
  405. "Character movement",
  406. "Vehicle simulation",
  407. "Destructible environments"
  408. ]
  409. }
  410. ```
  411. ### API Documentation
  412. The analyzer now includes comprehensive API documentation capabilities:
  413. 1. **Automatic Documentation Generation**
  414. - Extracts documentation from source code comments
  415. - Analyzes class structure and relationships
  416. - Categorizes classes by type and module
  417. - Generates syntax examples and usage patterns
  418. 2. **Smart Search**
  419. - Full-text search across all documentation
  420. - Relevance-based ranking of results
  421. - Category and module filtering
  422. - Code example inclusion
  423. 3. **Documentation Categories**
  424. - Object: Base object classes (UObject derivatives)
  425. - Actor: Actor classes (AActor derivatives)
  426. - Structure: Data structures and types
  427. - Component: Component classes
  428. - Miscellaneous: Other classes and utilities
  429. 4. **Module Organization**
  430. - Core: Core engine functionality
  431. - RenderCore: Rendering system
  432. - PhysicsCore: Physics engine
  433. - And other engine modules
  434. 5. **Integration with Existing Tools**
  435. - Links with class analysis for detailed information
  436. - Connects to pattern detection for best practices
  437. - References official Unreal Engine documentation
  438. - Provides learning resources and examples
  439. ### Best Practices
  440. 1. Always set either the Unreal Engine path or custom codebase path before using analysis tools
  441. 2. Use specific class names when analyzing (e.g., "MyClass" instead of just "Class")
  442. 3. Leverage the file pattern parameter in `search_code` to narrow down results
  443. 4. Include implemented interfaces when analyzing class hierarchies for complete understanding
  444. 5. Use the subsystem analysis tool to get a high-level overview before diving into specific classes (Unreal Engine only)
  445. ### Error Handling
  446. The analyzer will throw clear error messages when:
  447. - No codebase path is set (Unreal Engine or custom)
  448. - Provided path does not exist or is inaccessible
  449. - Class or symbol cannot be found in the codebase
  450. - Invalid file patterns are provided
  451. - Syntax errors in search queries or C++ code
  452. - Access to source files is restricted
  453. - Tree-sitter parsing fails for C++ files
  454. ### Performance Considerations
  455. - Large codebases may take longer to analyze
  456. - Complex class hierarchies might require more processing time
  457. - Broad search patterns could result in many matches
  458. - Consider using more specific queries for faster results
  459. ## Testing
  460. The project includes comprehensive test coverage for all major components:
  461. ### Test Coverage
  462. - **Analyzer Tests**: Core functionality tests for the UnrealCodeAnalyzer class
  463. - Initialization and path validation
  464. - Class analysis and parsing
  465. - Reference finding
  466. - Code searching
  467. - Subsystem analysis
  468. - Cache management
  469. - **Game Genres Tests**: Validation of the game genres knowledge base
  470. - Data structure verification
  471. - Genre-specific feature validation
  472. - Component naming conventions
  473. - Data completeness checks
  474. - **MCP Server Tests**: Testing of the MCP server implementation
  475. - Server initialization
  476. - Tool registration and handling
  477. - Request/response validation
  478. - Error handling
  479. - Tool-specific functionality tests
  480. ### Running Tests
  481. Run all tests:
  482. ```bash
  483. npm test
  484. ```
  485. Run tests in watch mode (useful during development):
  486. ```bash
  487. npm run test:watch
  488. ```
  489. ### Writing Tests
  490. When contributing new features, please ensure:
  491. 1. All new functionality has corresponding test coverage
  492. 2. Tests are organized in the `src/__tests__` directory
  493. 3. Mock external dependencies appropriately
  494. 4. Follow the existing test patterns for consistency
  495. ## Contributing
  496. Contributions are welcome! Please feel free to submit pull requests with improvements to:
  497. - Source code parsing capabilities
  498. - New analysis features
  499. - Performance optimizations
  500. - Documentation improvements
  501. - Test coverage
  502. Before submitting a PR:
  503. 1. Ensure all tests pass (`npm test`)
  504. 2. Add tests for new functionality
  505. 3. Update documentation as needed

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.