Skip to content

Commit 5d91cae

Browse files
NCMcClureNCMcClure
committed
feat: generalize AGENTS.md for any AI coding agent
- Rename title from CLAUDE.md to AGENTS.md - Generalize intro text to be agent-agnostic - Remove maintainer-specific Notion workspace section - Update README.md references to AGENTS.md - Add UE path detection scripts (Content/Scripts/) - Extend ue_python_finder.py with find_ue_source() function Developers can now run detect-ue-path.bat/.sh to auto-detect their UE installation and update AGENTS.md.
1 parent e775d97 commit 5d91cae

5 files changed

Lines changed: 342 additions & 11 deletions

File tree

‎AGENTS.md‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,22 @@
1-
# CLAUDE.md
1+
# AGENTS.md
22

3-
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
3+
This file provides guidance to AI coding agents when working with code in this repository.
44

55
# NodeToCode Unreal Engine 5 Plugin: Development Guide
66

77
# CRITICAL - START
88

9-
## @Development/Organization/notion-overview.md
10-
11-
This document acts as the central overview of the Protospatial Notion workspace which will be the ever-evolving planning/organization/documentation area for both you and myself to make sure that we're always keeping track of tasks, objectives, and goals.
12-
Always refer to the notion overview document at the beginning of a conversation so that you understand its structure, purpose, and how to navigate Notion workspace using the notionApi tool.
13-
149
## Understanding NodeToCode's MCP Server Tools
1510

16-
@Source/Private/MCP/Tools/README.md
11+
@Source/Private/MCP/Tools/AGENTS.md
1712

1813
## Unreal Engine Source Path
1914

20-
G:\UE\UE_5.4\Engine\Source : This is where source files for Unreal Engine 5 can be found and searched through for research purposes. NEVER try to modify files here.
15+
Run `Content/Scripts/detect-ue-path.sh` (Mac/Linux) or `Content\Scripts\detect-ue-path.bat` (Windows) to detect your UE installation and update this file.
16+
17+
UE_SOURCE_PATH: <!-- RUN DETECT SCRIPT TO POPULATE -->
18+
19+
This is where source files for Unreal Engine 5 can be found and searched through for research purposes. NEVER try to modify files here.
2120

2221
## TESTING COMPILATION
2322

@@ -457,7 +456,7 @@ curl -X POST http://localhost:27000/mcp \
457456

458457
#### Implementation Documentation
459458

460-
* **Tool Development Guide**: `Source/Private/MCP/Tools/README.md`
459+
* **Tool Development Guide**: `Source/Private/MCP/Tools/AGENTS.md`
461460
* Creating new tools with step-by-step instructions
462461
* Helper function reference
463462
* Best practices for Game Thread handling

‎Content/Python/mcp_bridge/ue_python_finder.py‎

Lines changed: 63 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
"""
1+
r"""
22
UE Python Finder
33
44
Finds Unreal Engine's bundled Python installation using the same methods
@@ -157,6 +157,68 @@ def get_python_path_for_ue_install(install_path: str, debug: bool = False) -> Op
157157
return None
158158

159159

160+
def get_source_path_for_ue_install(install_path: str, debug: bool = False) -> Optional[str]:
161+
"""
162+
Get the Engine/Source path for a given UE installation.
163+
"""
164+
source_path = os.path.join(install_path, 'Engine', 'Source')
165+
if os.path.isdir(source_path):
166+
log_debug(f"Found Source at: {source_path}", debug)
167+
return source_path
168+
169+
log_debug(f"Source not found at: {source_path}", debug)
170+
return None
171+
172+
173+
def find_ue_source(prefer_newest: bool = True, debug: bool = False) -> Optional[str]:
174+
"""
175+
Find UE Engine/Source path.
176+
177+
Args:
178+
prefer_newest: If True, prefer the newest UE version. If False, prefer oldest.
179+
debug: Enable debug logging.
180+
181+
Returns:
182+
Path to Engine/Source directory, or None if not found.
183+
"""
184+
all_installations = []
185+
186+
# Gather installations from all sources
187+
all_installations.extend(get_ue_installs_from_registry(debug))
188+
all_installations.extend(get_ue_installs_from_launcher(debug))
189+
190+
# Remove duplicates (by install path)
191+
seen_paths = set()
192+
unique_installations = []
193+
for version, path in all_installations:
194+
normalized_path = os.path.normpath(path).lower()
195+
if normalized_path not in seen_paths:
196+
seen_paths.add(normalized_path)
197+
unique_installations.append((version, path))
198+
199+
if not unique_installations:
200+
log_debug("No UE installations found via registry or launcher", debug)
201+
return None
202+
203+
# Sort by version
204+
unique_installations.sort(
205+
key=lambda x: parse_ue_version(x[0]),
206+
reverse=prefer_newest
207+
)
208+
209+
log_debug(f"Found {len(unique_installations)} UE installation(s)", debug)
210+
211+
# Find first installation with valid Source directory
212+
for version, install_path in unique_installations:
213+
source_path = get_source_path_for_ue_install(install_path, debug)
214+
if source_path:
215+
log_debug(f"Selected: {version} ({install_path})", debug)
216+
return source_path
217+
218+
log_debug("No UE installation has valid Source directory", debug)
219+
return None
220+
221+
160222
def parse_ue_version(version_str: str) -> Tuple[int, int, int]:
161223
"""
162224
Parse a UE version string into a tuple for sorting.

‎Content/Scripts/detect-ue-path.bat‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
@echo off
2+
REM NodeToCode UE Path Detector (Windows)
3+
REM Finds Unreal Engine installation and updates AGENTS.md
4+
REM Uses same Python detection methods as launch_bridge.bat
5+
6+
setlocal EnableDelayedExpansion
7+
8+
REM Get the directory where this script is located
9+
set "SCRIPT_DIR=%~dp0"
10+
set "PYTHON_SCRIPT=%SCRIPT_DIR%update_agents_ue_path.py"
11+
12+
REM Check if Python script exists
13+
if not exist "%PYTHON_SCRIPT%" (
14+
echo [detect-ue-path] ERROR: Python script not found at %PYTHON_SCRIPT%
15+
exit /b 1
16+
)
17+
18+
set "PYTHON_EXE="
19+
20+
REM === Method 1: Check Registry for Launcher-installed UE versions ===
21+
for %%V in (5.7 5.6 5.5 5.4 5.3) do (
22+
if "!PYTHON_EXE!"=="" (
23+
for /f "tokens=2*" %%A in ('reg query "HKEY_LOCAL_MACHINE\SOFTWARE\EpicGames\Unreal Engine\%%V" /v InstalledDirectory 2^>nul') do (
24+
set "UE_DIR=%%B"
25+
if exist "!UE_DIR!\Engine\Binaries\ThirdParty\Python3\Win64\python.exe" (
26+
set "PYTHON_EXE=!UE_DIR!\Engine\Binaries\ThirdParty\Python3\Win64\python.exe"
27+
echo [detect-ue-path] Found UE %%V Python via registry
28+
)
29+
)
30+
)
31+
)
32+
33+
REM === Method 2: Check Registry for Custom/Source builds ===
34+
if "!PYTHON_EXE!"=="" (
35+
for /f "tokens=1,2*" %%A in ('reg query "HKEY_CURRENT_USER\SOFTWARE\Epic Games\Unreal Engine\Builds" 2^>nul') do (
36+
if "!PYTHON_EXE!"=="" (
37+
if "%%B"=="REG_SZ" (
38+
set "UE_DIR=%%C"
39+
if exist "!UE_DIR!\Engine\Binaries\ThirdParty\Python3\Win64\python.exe" (
40+
set "PYTHON_EXE=!UE_DIR!\Engine\Binaries\ThirdParty\Python3\Win64\python.exe"
41+
echo [detect-ue-path] Found custom UE build Python via registry
42+
)
43+
)
44+
)
45+
)
46+
)
47+
48+
REM === Method 3: Check LauncherInstalled.dat ===
49+
if "!PYTHON_EXE!"=="" (
50+
set "LAUNCHER_FILE=%PROGRAMDATA%\Epic\UnrealEngineLauncher\LauncherInstalled.dat"
51+
if exist "!LAUNCHER_FILE!" (
52+
for /f "tokens=2 delims=:," %%A in ('type "!LAUNCHER_FILE!" ^| findstr /C:"InstallLocation"') do (
53+
if "!PYTHON_EXE!"=="" (
54+
set "INSTALL_PATH=%%~A"
55+
set "INSTALL_PATH=!INSTALL_PATH:"=!"
56+
set "INSTALL_PATH=!INSTALL_PATH: =!"
57+
if exist "!INSTALL_PATH!\Engine\Binaries\ThirdParty\Python3\Win64\python.exe" (
58+
set "PYTHON_EXE=!INSTALL_PATH!\Engine\Binaries\ThirdParty\Python3\Win64\python.exe"
59+
echo [detect-ue-path] Found UE Python via LauncherInstalled.dat
60+
)
61+
)
62+
)
63+
)
64+
)
65+
66+
REM === Method 4: Common installation paths ===
67+
if "!PYTHON_EXE!"=="" (
68+
set "UE_PATHS=C:\Program Files\Epic Games;D:\Program Files\Epic Games;E:\Program Files\Epic Games"
69+
set "UE_PATHS=!UE_PATHS!;C:\Epic Games;D:\Epic Games;E:\Epic Games"
70+
set "UE_PATHS=!UE_PATHS!;C:\UE;D:\UE;E:\UE;F:\UE;G:\UE"
71+
72+
set "UE_VERSIONS=UE_5.7 UE_5.6 UE_5.5 UE_5.4 UE_5.3 UE_5.2 UE_5.1 UE_5.0"
73+
74+
for %%P in (!UE_PATHS!) do (
75+
for %%V in (!UE_VERSIONS!) do (
76+
if "!PYTHON_EXE!"=="" (
77+
set "TEST_PATH=%%P\%%V\Engine\Binaries\ThirdParty\Python3\Win64\python.exe"
78+
if exist "!TEST_PATH!" (
79+
set "PYTHON_EXE=!TEST_PATH!"
80+
echo [detect-ue-path] Found UE Python at common path
81+
)
82+
)
83+
)
84+
)
85+
)
86+
87+
REM === Method 5: System Python ===
88+
if "!PYTHON_EXE!"=="" (
89+
where python >nul 2>&1
90+
if !ERRORLEVEL! EQU 0 (
91+
set "PYTHON_EXE=python"
92+
echo [detect-ue-path] Using system Python
93+
)
94+
)
95+
96+
if "!PYTHON_EXE!"=="" (
97+
where python3 >nul 2>&1
98+
if !ERRORLEVEL! EQU 0 (
99+
set "PYTHON_EXE=python3"
100+
echo [detect-ue-path] Using system Python3
101+
)
102+
)
103+
104+
REM === No Python found ===
105+
if "!PYTHON_EXE!"=="" (
106+
echo [detect-ue-path] ERROR: Python not found.
107+
echo [detect-ue-path] Please install Unreal Engine or Python.
108+
exit /b 1
109+
)
110+
111+
REM Run the Python script to update AGENTS.md
112+
echo [detect-ue-path] Running UE path detection...
113+
"!PYTHON_EXE!" "%PYTHON_SCRIPT%" %*

‎Content/Scripts/detect-ue-path.sh‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
#!/bin/bash
2+
# NodeToCode UE Path Detector (macOS/Linux)
3+
# Finds Unreal Engine installation and updates AGENTS.md
4+
# Uses same Python detection methods as launch_bridge.sh
5+
6+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
7+
PYTHON_SCRIPT="$SCRIPT_DIR/update_agents_ue_path.py"
8+
9+
# Check if Python script exists
10+
if [ ! -f "$PYTHON_SCRIPT" ]; then
11+
echo "[detect-ue-path] ERROR: Python script not found at $PYTHON_SCRIPT"
12+
exit 1
13+
fi
14+
15+
PYTHON_EXE=""
16+
17+
# === Try to find UE's bundled Python ===
18+
19+
# Common UE installation paths on macOS
20+
UE_PATHS=(
21+
"/Users/Shared/Epic Games"
22+
"$HOME/Epic Games"
23+
"/Applications/Epic Games"
24+
)
25+
26+
# UE versions to check (newest first)
27+
UE_VERSIONS=("UE_5.7" "UE_5.6" "UE_5.5" "UE_5.4" "UE_5.3" "UE_5.2" "UE_5.1" "UE_5.0")
28+
29+
for ue_path in "${UE_PATHS[@]}"; do
30+
for ue_version in "${UE_VERSIONS[@]}"; do
31+
TEST_PATH="$ue_path/$ue_version/Engine/Binaries/ThirdParty/Python3/Mac/bin/python3"
32+
if [ -f "$TEST_PATH" ]; then
33+
PYTHON_EXE="$TEST_PATH"
34+
echo "[detect-ue-path] Found UE Python: $PYTHON_EXE"
35+
break 2
36+
fi
37+
done
38+
done
39+
40+
# === Fall back to system Python ===
41+
42+
if [ -z "$PYTHON_EXE" ]; then
43+
if command -v python3 &> /dev/null; then
44+
PYTHON_EXE="python3"
45+
echo "[detect-ue-path] Using system Python3"
46+
elif command -v python &> /dev/null; then
47+
PYTHON_EXE="python"
48+
echo "[detect-ue-path] Using system Python"
49+
else
50+
echo "[detect-ue-path] ERROR: Python not found. Please install Python or Unreal Engine."
51+
exit 1
52+
fi
53+
fi
54+
55+
# Run the Python script to update AGENTS.md
56+
echo "[detect-ue-path] Running UE path detection..."
57+
exec "$PYTHON_EXE" "$PYTHON_SCRIPT" "$@"

‎Content/Scripts/update_agents_ue_path.py‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
"""
2+
Update AGENTS.md with Unreal Engine Source Path
3+
4+
This script detects the UE installation and updates the AGENTS.md file
5+
with the correct Engine/Source path.
6+
7+
Uses ue_python_finder.py for UE detection.
8+
"""
9+
10+
import os
11+
import sys
12+
import re
13+
14+
# Add mcp_bridge to path to import ue_python_finder
15+
script_dir = os.path.dirname(os.path.abspath(__file__))
16+
plugin_root = os.path.dirname(os.path.dirname(script_dir))
17+
mcp_bridge_path = os.path.join(plugin_root, 'Content', 'Python', 'mcp_bridge')
18+
sys.path.insert(0, mcp_bridge_path)
19+
20+
from ue_python_finder import find_ue_source
21+
22+
23+
def update_agents_md(source_path: str, agents_md_path: str) -> bool:
24+
"""
25+
Update the UE_SOURCE_PATH line in AGENTS.md.
26+
27+
Args:
28+
source_path: The UE Engine/Source path to set
29+
agents_md_path: Path to AGENTS.md file
30+
31+
Returns:
32+
True if successful, False otherwise
33+
"""
34+
if not os.path.exists(agents_md_path):
35+
print(f"Error: AGENTS.md not found at {agents_md_path}", file=sys.stderr)
36+
return False
37+
38+
try:
39+
with open(agents_md_path, 'r', encoding='utf-8') as f:
40+
content = f.read()
41+
42+
# Pattern to match the UE_SOURCE_PATH line
43+
# Matches: UE_SOURCE_PATH: <anything until end of line>
44+
pattern = r'^UE_SOURCE_PATH:.*$'
45+
# Escape backslashes in path for regex replacement
46+
escaped_path = source_path.replace('\\', '\\\\')
47+
replacement = f'UE_SOURCE_PATH: {escaped_path}'
48+
49+
new_content, count = re.subn(pattern, replacement, content, flags=re.MULTILINE)
50+
51+
if count == 0:
52+
print("Warning: UE_SOURCE_PATH line not found in AGENTS.md", file=sys.stderr)
53+
return False
54+
55+
with open(agents_md_path, 'w', encoding='utf-8') as f:
56+
f.write(new_content)
57+
58+
print(f"Successfully updated AGENTS.md with UE source path: {source_path}")
59+
return True
60+
61+
except Exception as e:
62+
print(f"Error updating AGENTS.md: {e}", file=sys.stderr)
63+
return False
64+
65+
66+
def main():
67+
import argparse
68+
69+
parser = argparse.ArgumentParser(description='Update AGENTS.md with UE source path')
70+
parser.add_argument('--debug', action='store_true', help='Enable debug output')
71+
parser.add_argument('--agents-md', type=str, help='Path to AGENTS.md (auto-detected if not specified)')
72+
args = parser.parse_args()
73+
74+
# Auto-detect AGENTS.md path
75+
if args.agents_md:
76+
agents_md_path = args.agents_md
77+
else:
78+
# Default to plugin root AGENTS.md
79+
agents_md_path = os.path.join(plugin_root, 'AGENTS.md')
80+
81+
if args.debug:
82+
print(f"Looking for AGENTS.md at: {agents_md_path}", file=sys.stderr)
83+
84+
# Find UE source path
85+
source_path = find_ue_source(prefer_newest=True, debug=args.debug)
86+
87+
if not source_path:
88+
print("Error: Could not find Unreal Engine installation", file=sys.stderr)
89+
print("Please install Unreal Engine or manually set UE_SOURCE_PATH in AGENTS.md", file=sys.stderr)
90+
sys.exit(1)
91+
92+
# Update AGENTS.md
93+
if update_agents_md(source_path, agents_md_path):
94+
sys.exit(0)
95+
else:
96+
sys.exit(1)
97+
98+
99+
if __name__ == '__main__':
100+
main()

0 commit comments

Comments
 (0)