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

Authoritative repository: [Metalroachtwo/Assetto-Corsa-Replay-MCP](https://github.com/Metalroachtwo/Assetto-Corsa-Replay-MCP). Development workflow: [CONTRIBUTING.md](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](docs/VALIDATION_V0.2.2.md).
- 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.

## 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):

```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

```powershell
.\.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](docs/VALIDATION_V0.2.2.md) 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.

```powershell
.\.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:

```json
{
  "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](https://github.com/gro-ove/actools/blob/master/AcManager/Tools/ArgumentsHandler.cs) 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](docs/VALIDATION_V0.2.2.md) distinguish source review, synthetic tests and unverified live CSP behavior. Historical changes are in [CHANGELOG.md](CHANGELOG.md).