Assetto Corsa Cinematic Director MCP — v0.2.2 (CSP bridge hardening)

Authoritative repository: Metalroachtwo/Assetto-Corsa-Replay-MCP. Development workflow: CONTRIBUTING.md.

Standalone freeware/open-source MCP server for read-only installation discovery, cinematic planning, replay preflight, and an optional CSP Lua replay-status bridge. Any compatible MCP client can use it; Friday is the first field tester.

It does not launch or play replays, change PP filters, move cameras or record footage yet. All mutations are blocked, even if a mod appears installed.

v0.2.2 update

• Corrected three findings from Friday’s v0.2.1 audit: removed the unverified Lua JSON dependency, checked io.save() failure return values as well as exceptions, and rejected all future-dated snapshot mtimes (no two-second grace).

• The new Lua source serializes only fixed schema-v1 status fields and escapes JSON strings locally. No external JSON package or copied OBS Helper implementation is required.

• Source review confirms explicit write-failure guards; installed CSP LuaJIT execution and live file writing remain unverified. See the exact evidence limits in v0.2.2 validation.

• The original 15 read-only/safety-gated MCP tools and all control restrictions are unchanged. No launcher, camera, PP-filter switch or recording behavior has been enabled.

• Windows validation: 40 passed, 3 symlink skips, 0 failures across 43 unit tests. The real MCP v2 stdio smoke passed 15 tool listings, 15 calls and clean shutdown using SDK 2.3.0. Live deployment remains a separate authorization gate.

Related MCP server: ue-bridge

v0.2.1 update

• Adds probe_replay_bridge and get_live_replay_status (15 tools total), with bounded local JSON snapshot validation, freshness checks, schema validation, symlink protection and no game-process manipulation.

• Includes an optional, uninstalled Lua app prototype in csp_bridge/AssettoCinematicBridge/. The Lua native calls must be checked against the player's installed CSP SDK and validated live only after separate authorization. No app or game configuration is changed by the MCP.

• Does not integrate with or depend on OBS Helper; its GPU texture shared memory is not a command channel.

• See docs/CSP_BRIDGE_PROTOCOL.md and docs/FRIDAY_VALIDATION.md. The original 13 tools and all safety placeholders remain unchanged.

v0.2.0 features retained

• Recognizes default AC cameras, CamTool 2, name-matched Drone/FPV apps, and 11 known camera utilities in CSP Lua/Python, chaser and cockpit mod folders.

• Reads saved Python-app ACTIVE=0/1 flags, prioritizing the player's Documents/Assetto Corsa/cfg/python.ini over the game-root fallback per app. Reports the relative source (enabled_source). A saved enabled flag is not proof a mod works in-game.

• Detects CamTool's 1.14.3 x64-style docstring header and best-effort IS_DroneCam version headers without executing mod code.

• Inventories CamTool presets, PP filters, configured (not runtime) PP filter, and replay file counts.

• Discovers Windows' redirected Documents directory via the Documents known-folder API, with explicit override support.

• Attempts safe read-only detection of CSP/Content Manager Windows file versions and Pure manifests. These can be null when metadata is absent, ambiguous or unavailable.

• Preserves the 11 original MCP tool names, and retains list_saved_replays and prepare_replay_launch (13 original/previous tools), while retaining prior schema_version: "0.1" response keys. New response fields are additive: documents, pure, weather, additional cameras, version/enabled metadata.

• Adds a safe, filename-only, paginated saved-replay inventory and read-only Content Manager launch preflight. Refuses traversal paths, files outside the selected replay folder and invalid executable candidates. It never starts the game. The Content Manager positional file-argument route is verified in upstream source, not yet against the player's installed binary.

• Retains the bounded diagnostic real MCP stdio smoke test against a synthetic, temporary Assetto Corsa fixture. Stages are logged on stderr; a supervisor enforces a 60-second hard deadline, including connection and shutdown, and terminates only the smoke-test worker process tree if it stalls. Does not require your game installation.

Requirements and first install (Windows)

Python 3.11 or later (Friday's previous report found Python 3.14.6), with internet access once to install dependencies. Check the intended interpreter before creating a virtual environment.

In the extracted project folder (PowerShell):

py -3 --version
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m pip show mcp

Do not use Python 3.10, which is below the required version. A network or package-registry failure is an unresolved install blocker, not a reason to alter the game installation. Use an isolated environment, not a system-wide pip install.

Test v0.2.2 without launching the game

.\.venv\Scripts\python.exe scripts\verify_release.py
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe scripts\mcp_smoke_test.py

The smoke command must report PASS, 15 listed tools and 15 calls checked, with clean shutdown using the real MCP v2 SDK over stdio. A missing SDK is BLOCKED; a timeout or partial progress is not a pass. The supervisor bounds startup and shutdown with a 60-second deadline plus termination cleanup. These checks use temporary synthetic fixtures and never start the game, Content Manager, OBS or a camera mod. See current validation for exact results and coverage limits.

Optional real-install read-only discovery

The scanner uses an explicit path override, AC_GAME_DIR, or conventional Steam libraries. It resolves the redirected Documents path using the Windows Known Folder interface, but can still be overridden.

.\.venv\Scripts\assetto-cinematic-scan.exe --game-dir "<ASSETTO_CORSA_ROOT>" --documents-dir "<DOCUMENTS_ASSETTO_CORSA_FOLDER>"

Alternatively, use environment variables AC_GAME_DIR, AC_DOCUMENTS_DIR, CONTENT_MANAGER_EXE, OBS_EXE, FFMPEG_EXE, STEAM_DIR. The scanner does not launch CM or check that an installed mod is operational.

Output hides local absolute paths by default. Do not share --include-paths output publicly. Mod/preset names can be personal; inspect the report before publishing it.

MCP host example

Substitute your own installed venv interpreter and installation directories, then add the entry to your host's existing MCP configuration:

{
  "mcpServers": {
    "assetto-cinematic": {
      "command": "<FULL_PATH_TO_VENV_PYTHON_EXE>",
      "args": ["-m", "assetto_cinematic_mcp.server"],
      "env": {
        "AC_GAME_DIR": "<ASSETTO_CORSA_ROOT>",
        "AC_DOCUMENTS_DIR": "<DOCUMENTS_ASSETTO_CORSA_FOLDER>",
        "CONTENT_MANAGER_EXE": "<CONTENT_MANAGER_EXECUTABLE>"
      }
    }
  }
}

This is a generic shape; follow the actual MCP host's settings format. Only enable the host entry once the stdio smoke test passes. An MCP client can call the read-only tools; it cannot cause game modifications using v0.2.2.

Exposed MCP tools

scan_environment, list_camera_tools, list_camera_presets, list_pp_filters, validate_camera_capability, validate_filter_compatibility, create_cinematic_plan, activate_camera, set_pp_filter, capture_replay_shot, restore_original_configuration, list_saved_replays, prepare_replay_launch, probe_replay_bridge, get_live_replay_status.

Both new bridge tools are read-only and validate an optional status file only. The original mutation tools intentionally decline operation or are a no-op. activate_camera, set_pp_filter and capture_replay_shot return executed=false. restore_original_configuration returns changed=false. No remote control interface is claimed or used.

list_saved_replays(game_dir="", documents_dir="", offset=0, limit=25) returns direct-child .acreplay filenames, sizes and modification times (no absolute paths); limit is 1–100. prepare_replay_launch(replay_name, game_dir="", documents_dir="", content_manager_exe="") verifies a selected filename and existing CM executable, returns an unexecuted launch shape with ready_for_authorized_test; this flag does not mean the replay works or live operation is approved. Both tools are read-only. Set CONTENT_MANAGER_EXE for the executable candidate or supply it explicitly.

Source evidence: CM ArgumentsHandler dispatches a file argument ending in .acreplay to GameWrapper.StartReplayAsync. This does not establish the behavior of an installed Content Manager build. Do not use acs.exe directly or automate the GUI.

Safety and licensing

• No game/CM/OBS startup, keyboard/mouse automation, injection, memory patches, DLL loading, or config modifications.

• Probe only known directories and text manifests; no arbitrary mod code execution or credential disclosure.

• The project code is Unlicense (see LICENSE). Camera mods, CM, CSP, Pure, OBS and FFmpeg are not bundled. Review upstream licenses before embedding third-party code.

• Different camera tools can fight for camera ownership. Runtime adapters must wait until a later authorized, isolated test phase.

Known issues and next gates

Friday confirmed v0.1.2's SDK 2.3.0 stdio transport, 11 real tools and 11 successful calls on 2026-11-07. v0.2.1 added two status tools and Friday verified all 15 through real stdio; v0.2.2 preserves those interfaces. Live game integration remains unverified. Native CSP replay readback is implemented only as an optional, not field-tested Lua snapshot prototype; Content Manager's .acreplay file-argument dispatch is still a research candidate, not implemented as a launcher. PP filter selection has no validated setter. OBS WebSocket remains deliberately untouched.

See docs/FRIDAY_VALIDATION.md, docs/ARCHITECTURE.md, docs/LOCAL_TEST_RESULTS.md and CHANGELOG.md.

Validation and remaining gates

The v0.2.2 Windows regression passed 40 tests with 3 symlink skips, and all 15 real stdio calls completed cleanly. Validation details distinguish source review, synthetic tests and unverified live CSP behavior. Historical changes are in CHANGELOG.md.