ac-race-engineer

MCP 서버로, Claude를 오리지널 Assetto Corsa의 레이스 엔지니어로 변환합니다. AC의 공유 메모리 텔레메트리를 읽고, SQLite에 랩을 저장하며, 이를 엔지니어 수준의 요약으로 축소하고, 게임 내 설정 메뉴에 직접 표시되는 설정 파일을 읽고 쓸 수 있습니다.

Assetto Corsa가 실행 중인 Windows 머신에서 실행됩니다. 오리지널 AC만 해당(acpmf_* 공유 메모리 레이아웃 사용, ACC는 아님).

설치 (Windows — 쉬운 방법)

필수 조건: python.org의 Python 3.10+. 설치 프로그램의 첫 화면에서 **"Add python.exe to PATH"**를 체크하세요. Microsoft Store 빌드를 사용하지 마세요. 샌드박싱이 공유 메모리 접근을 차단합니다.

그런 다음, 이 폴더에서: install-windows.bat를 우클릭 → 열기 (또는 그냥 더블클릭).

끝입니다. 설치 프로그램이 Python을 찾고, 패키지를 설치하고, Claude Desktop 설정을 작성하고(기존 MCP 서버와 병합하고 먼저 백업을 수행), Assetto Corsa 설치 위치를 찾아 게임 내 Lua 앱을 복사합니다. git pull 후 언제든 다시 실행하면 됩니다. 제자리에서 업데이트됩니다.

Assetto Corsa를 찾을 수 없으면 위치를 알려주세요. 플래그는 .bat에 사용하고, .ps1에는 사용하지 마세요. Windows는 기본 실행 정책에서 .ps1 파일을 직접 실행하지 못하도록 차단하며, .bat은 바로 그 문제를 해결하기 위해 존재합니다:

install-windows.bat -AcPath "D:\Games\steamapps\common\assettocorsa"

기타 플래그: -SkipLuaApp, -Uninstall.

설치 후 Claude Desktop을 완전히 종료하고 다시 여세요. 창을 닫는 것만으로는 충분하지 않습니다. 시스템 트레이(오른쪽 아래, ^ 화살표 아래에 숨겨져 있을 수 있음)에서 Claude 아이콘을 우클릭하고 종료를 선택하세요.

Related MCP server: fastf1-mcp-server

설치 (수동)

python -m pip install -e .

그런 다음 서버를 claude_desktop_config.json에 추가합니다. 이 파일을 여는 가장 빠른 방법은 Claude Desktop → Settings → Developer → Edit Config입니다. 이렇게 하면 파일이 없으면 생성되고, 폴더가 열리므로 파일 시스템 탐색이 필요하지 않습니다.

%APPDATA%는 환경 변수이지 리터럴 경로가 아닙니다. C:\Users\<사용자>\AppData\Roaming으로 확장됩니다. 그리고 AppData는 숨김 폴더이므로 Explorer에서 보려면 View → Hidden items를 활성화하지 않으면 아무것도 표시되지 않습니다.

더 큰 문제는 %VAR%가 cmd.exe 구문이라는 점입니다. Windows Terminal은 기본적으로 PowerShell을 사용하며, 동일한 변수는 $env:VAR로 표기됩니다. 따라서:

파일 대신 폴더를 열려면 PowerShell에서 explorer $env:APPDATA\Claude를 사용하세요.

{
  "mcpServers": {
    "ac-race-engineer": {
      "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
      "args": ["-m", "ac_race_engineer.server"]
    }
  }
}

python.exe의 절대 경로를 사용하고, 단순히 "python"을 사용하지 마세요. Claude Desktop은 셸의 PATH 없이 MCP 서버를 실행하므로, 단순 명령은 자주 조용히 실패합니다. 올바른 경로를 얻으려면:

py -c "import sys; print(sys.executable)"

(Get-Command python).Source를 사용하지 마세요. 일반적인 Windows에서는 ...\WindowsApps\python.exe(Microsoft Store 별칭 스텁)을 반환하는 경우가 많으며, 이는 잘못된 답변입니다. JSON에서는 백슬래시를 두 배로(\\) 해야 합니다.

(Claude Code를 사용하는 경우: claude mcp add ac-race-engineer -- python -m ac_race_engineer.server)

선택적 환경 변수 재정의:

• AC_DOCS_DIR — AC 문서 폴더 (기본값 ~/Documents/Assetto Corsa)

• AC_ENGINEER_DATA — DB + 범위 위치 (기본값 ~/.ac-race-engineer)

• AC_ENGINEER_BRIDGE_PORT — 게임 내 앱 브리지 포트 (기본값 9666)

문제 해결

Claude가 도구를 나열하지 않습니다. Claude Desktop을 완전히 종료하고 다시 열었는지 확인하세요(트레이 아이콘 → 종료). 그런 다음 서버 로그를 읽으세요:

notepad $env:APPDATA\Claude\logs\mcp-server-ac-race-engineer.log

python을 입력하면 Microsoft Store가 열립니다(또는 "인식되지 않음"이라고 표시됨). Windows는 %LOCALAPPDATA%\Microsoft\WindowsApps\python.exe에 앱 실행 별칭 스텁을 제공하여, 실제 Python이 PATH에 없을 때 이름을 가로챕니다. python.org에서 Python을 설치할 때 "Add python.exe to PATH"를 체크하거나, py 런처(py -3 -m pip install -e .)를 사용하세요. python.org 설치 프로그램이 기본적으로 이를 설정합니다. Settings → Apps → Advanced app settings → App execution aliases에서 스텁을 비활성화할 수도 있습니다.

설치 프로그램은 이미 WindowsApps 아래의 모든 것을 무시하므로, 수동 설치 시에만 문제가 됩니다.

.ps1 cannot be loaded because running scripts is disabled. 실행 정책 때문입니다. 대신 install-windows.bat를 사용하세요. 시스템 설정을 변경하지 않고 해당 스크립트에 대해서만 정책을 우회합니다.

설정 값이 게임 내에서 적용되지 않습니다. 차량의 합법 범위를 벗어난 값을 쓰고 있으며 AC가 조용히 무시하고 있습니다. 다음 섹션을 참조하세요.

튜닝 루프

1. AC를 시작하고 트랙에 진입하세요.

2. Claude에게 "start recording and confirm you can see the session"라고 말하세요(start_recording, live_snapshot).

3. 3–5랩을 주행하세요. 랩은 완료되면 자동으로 저장됩니다. 트랙 이탈(타이어 2개 이상 아웃)은 랩을 무효로 표시합니다.

4. "Summarize my last lap and read my current setup"(list_laps, lap_summary, read_setup). 요약에는 코너별 최저 속도, 브레이크 지점, 타이어 압력/온도, 슬립 밸런스 메트릭(양수 = 언더스티어, 음수 = 오버스티어)이 포함됩니다.

5. 차량의 상태를 논의하고, Claude는 write_setup으로 수정된 설정을 작성합니다(예: claude_v1).

6. 피트로 들어와 설정 화면에서 claude_v1을 불러온 후 다시 주행하세요.

7. "Compare my best lap on the new setup against lap N"(compare_laps) — 코너별 최저 속도와 브레이크 지점 델타가 변경이 실제로 효과가 있었는지 보여줍니다.

설정 값 클램핑 (권장)

AC는 차량의 setup.ini(data.acd 내부)에 정의된 범위를 벗어난 설정 값을 조용히 무시합니다. 서버가 각 차량의 합법적인 최소/최대/단계로 값을 클램핑하고 스냅하도록 하려면:

1. Content Manager에서: 차량 페이지 → unpack data (또는 QuickBMS 사용).

2. 차량의 setup.ini를 ranges 폴더에 복사하고, 차량 폴더 이름으로 이름을 지정하세요. 예: ks_mazda_mx5_cup.ini.

해당 폴더를 열려면(설치 프로그램이 이미 생성했습니다):

explorer $env:USERPROFILE\.ac-race-engineer\ranges

(cmd.exe: explorer %USERPROFILE%\.ac-race-engineer\ranges)

ranges 파일이 없어도 쓰기는 작동하지만 경고와 함께 반환되며, 설정 화면에서 값을 직접 확인해야 합니다.

게임 내 앱 (CSP Lua)

install-windows.bat가 자동으로 복사합니다. 수동으로 하려면 lua_app/race_engineer/를 assettocorsa/apps/lua/race_engineer/로 복사하세요(Custom Shaders Patch 필요; CSP를 활성화한 Content Manager를 사용하는 경우 이미 설치되어 있습니다). 세션 중 화면 오른쪽 가장자리로 마우스를 이동하면 나타나는 게임 내 앱 사이드바에서 활성화하세요.

Assetto Corsa가 설치된 위치를 모르시나요? Steam에서 Assetto Corsa를 우클릭 → Manage → Browse local files.

기능:

• 주행 중 불만 태그 — 언더스티어 / 오버스티어 / 브레이킹 / 트랙션 버튼. 각각 앱의 설정 창을 통해 휠 버튼에 바인딩할 수 있습니다(CSP 컨트롤 바인딩으로 표시됨). 버튼을 누르면 정확한 스플라인 위치, 랩, 속도가 기록됩니다. Claude는 get_driver_notes로 이를 읽고 코너 텔레메트리와 연관시킵니다: "스플라인 0.34에서 언더스티어를 두 번 표시했습니다. 이는 프론트 슬립이 리어보다 0.09 초과하는 코너입니다."

• 상태 오버레이 — 녹화 표시기 + 저장된 랩 수. 확인을 위해 알트탭할 필요가 없습니다.

• Claude의 메시지 — send_driver_message가 오버레이에 메모를 표시합니다("claude_v2 저장됨 — 피트로 들어와서 로드하세요"); 확인(OK)으로 닫습니다.

앱은 서버의 HTTP 브리지와 127.0.0.1:9666에서 통신합니다(AC_ENGINEER_BRIDGE_PORT로 변경하고, Lua의 BASE도 일치시켜 수정). 브리지는 localhost만 바인딩합니다.

구조

ac_race_engineer/
  sim_info.py   shared memory structs (physics / graphics / static)
  collector.py  background sampler -> SQLite, lap boundary detection
  db.py         schema + storage
  analysis.py   corner detection, lap summaries, lap comparison
  setups.py     setup INI read/write, range clamping
  bridge.py     localhost HTTP bridge for the in-game app
  server.py     MCP tools
lua_app/
  race_engineer/  CSP Lua in-game app (copy to apps/lua/)
install-windows.ps1  one-shot Windows installer
install-windows.bat  double-clickable wrapper for the above

참고 사항 / 향후 아이디어

• 샘플링은 25Hz입니다. DB를 작게 유지하면서 설정 작업에 충분합니다. 더 세밀한 트레이스를 원한다면 collector.py에서 TARGET_HZ를 높이세요.

• 아웃랩(유효 시간 없음)은 자동으로 건너뜁니다.

• 코너 감지는 일반적입니다(속도 최소값). 트랙별 코너 이름 맵이 있으면 Claude의 조언이 더 읽기 좋아집니다("T3/Variante" vs "0.34 지점의 코너").

• CSP/Lua는 댐퍼 속도 및 표준 공유 메모리보다 더 많은 채널을 노출할 수 있습니다. 더 깊은 서스펜션 작업을 원한다면 Telemetrick의 소스가 좋은 참고 자료입니다.