# BeamNG Modding MCP

A local Model Context Protocol server for researching, scaffolding, reviewing, validating, and packaging BeamNG.drive mods. Official BeamNG documentation results include their source URL and freshness metadata; optional game-source searches are read-only.

## Requirements and setup

- Node.js 20 or newer
- A directory dedicated to your mod projects

```bash
cd /Users/joaorodrigues/Documents/beamng-mcp
npm install
npm run build
```

Choose a workspace. Every server write is confined to this directory:

```bash
mkdir -p /absolute/path/to/beamng-mod-workspace
```

Optional environment variables:

| Variable | Purpose |
| --- | --- |
| `BEAMNG_MOD_ROOT` | Required writable mod workspace |
| `BEAMNG_GAME_ROOT` | Optional read-only BeamNG installation/content root |
| `BEAMNG_DOCS_CACHE` | Optional documentation cache location |
| `BEAMNG_DOCS_TTL_HOURS` | Cache freshness interval; defaults to 24 |

## Connect an MCP client

Replace `/absolute/path/to/beamng-mod-workspace` in these examples.

### Codex

The installed Codex CLI can create the stdio registration directly:

```bash
codex mcp add beamng-modding \
  --env BEAMNG_MOD_ROOT=/absolute/path/to/beamng-mod-workspace \
  -- node /Users/joaorodrigues/Documents/beamng-mcp/dist/index.js
```

Add optional environment variables by repeating `--env`. Confirm the registration with:

```bash
codex mcp get beamng-modding
```

Start a new Codex task after adding the server so its tools are discovered.

### Claude Desktop

Add this server under `mcpServers` in Claude Desktop's MCP configuration:

```json
{
  "mcpServers": {
    "beamng-modding": {
      "command": "node",
      "args": ["/Users/joaorodrigues/Documents/beamng-mcp/dist/index.js"],
      "env": {
        "BEAMNG_MOD_ROOT": "/absolute/path/to/beamng-mod-workspace"
      }
    }
  }
}
```

Restart Claude Desktop after saving the configuration.

### Cursor

Create `.cursor/mcp.json` in the project that should use the server:

```json
{
  "mcpServers": {
    "beamng-modding": {
      "command": "node",
      "args": ["/Users/joaorodrigues/Documents/beamng-mcp/dist/index.js"],
      "env": {
        "BEAMNG_MOD_ROOT": "/absolute/path/to/beamng-mod-workspace"
      }
    }
  }
}
```

### VS Code

Create `.vscode/mcp.json`:

```json
{
  "servers": {
    "beamng-modding": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/joaorodrigues/Documents/beamng-mcp/dist/index.js"],
      "env": {
        "BEAMNG_MOD_ROOT": "/absolute/path/to/beamng-mod-workspace"
      }
    }
  }
}
```

Run **MCP: List Servers** from the Command Palette to start or inspect it.

## First use

Populate the local official-documentation index. Either ask the client:

> Synchronize the BeamNG modding documentation with `beamng_docs_sync`, then find the official guidance for creating a vehicle configuration.

Or run the CLI task with the same environment:

```bash
BEAMNG_MOD_ROOT=/absolute/path/to/beamng-mod-workspace npm run docs:sync
```

The server keeps cached pages available when offline. Refreshes are same-origin and restricted to `https://documentation.beamng.com/modding/`.

Example requests:

- “Plan a BeamNG Lua extension, citing the official docs.”
- “Dry-run a vehicle mod scaffold named `rally_buggy` in `rally-buggy`.”
- “Validate the mod in `rally-buggy` and explain every error with sources.”
- “Search my configured BeamNG source for `onExtensionLoaded` examples.”
- “Package `rally-buggy` as `releases/rally-buggy.zip` after it passes validation.”

Scaffolding and general file writes default to `dryRun: true`. Ask explicitly to apply the operation after reviewing the planned paths.

## Tools

| Tool | Purpose |
| --- | --- |
| `beamng_docs_search` | Search the synchronized official documentation |
| `beamng_docs_get` | Read a cached page/section or fetch one approved URL |
| `beamng_docs_sync` | Refresh the bounded documentation cache |
| `beamng_source_search` | Search optional local game text files read-only |
| `beamng_mod_scaffold` | Generate one of seven text-only mod templates |
| `beamng_mod_write_files` | Atomically write bounded UTF-8 changes |
| `beamng_mod_validate` | Check structure, JBeam, JSON, materials, references, and metadata |
| `beamng_mod_package` | Validate and create a deterministic ZIP |
| `beamng_best_practices` | Return evidence-backed rules by mod type/topic |

The server also publishes documentation, templates, best practices, and the latest validation report as MCP resources, plus four reusable workflow prompts.

## Development

```bash
npm run check
```

The tests cover path traversal and symlink containment, atomic overwrite behavior, documentation extraction/search, tolerant JBeam parsing, all scaffold profiles, deterministic archive layout, and MCP discovery/tool execution.

## Safety and limitations

- The server never installs mods or changes BeamNG game files.
- All authoring paths are relative to `BEAMNG_MOD_ROOT`; symlink escapes and traversal are rejected.
- Static validation cannot prove physics, rendering, Lua runtime behavior, or gameplay correctness. Test the packaged ZIP in BeamNG.drive.
- Documentation is incomplete in some areas. Official docs, configured local game source, and curated guidance are always labeled separately.