# opendrive-mcp-server

`opendrive-mcp-server` exposes deterministic OpenDRIVE inspection tools through the Model Context
Protocol (MCP). It is designed for agents and applications that need structured road-network queries
without asking an LLM to parse or edit `.xodr` XML directly.

The first-stage backend is [`pageldev/libOpenDRIVE`](https://github.com/pageldev/libOpenDRIVE),
called through small C++ CLI tools. The default backend is the real libOpenDRIVE-backed `cli`
backend; mock output is not valid acceptance evidence.

This project is not affiliated with the original libOpenDRIVE project unless stated otherwise.

## What It Does

- Opens OpenDRIVE files with libOpenDRIVE.
- Lists roads and lanes.
- Converts OpenDRIVE road coordinates to world coordinates.
- Runs basic parse and road/lane sanity checks.
- Returns machine-readable JSON through MCP tools.
- Writes trace records to `runs/<run_id>/trace.jsonl`.

## What It Does Not Do

- It does not edit OpenDRIVE XML.
- It does not provide an OpenDRIVE XML generation reference for LLMs.
- It does not accept free-form natural-language map modification requests.
- It does not generate OpenSCENARIO.
- It does not contain scenario-specific business logic.
- It does not call LLMs inside the MCP server.

## Requirements

- Python 3.11+
- CMake with a C++17 compiler
- `pageldev/libOpenDRIVE` available at `third_party/libOpenDRIVE`
- Optional for local acceptance: Ollama with a local Qwen model

## Install

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
```

Fetch the first-stage backend. If you cloned this repository with submodules:

```bash
git submodule update --init --recursive
```

If you are working from a source archive without submodule metadata:

```bash
git clone https://github.com/pageldev/libOpenDRIVE third_party/libOpenDRIVE
```

Build the libOpenDRIVE-backed CLI tools:

```bash
cmake -S . -B build
cmake --build build
```

The build creates:

- `build/cpp/opendrive_tools/odr-summary`
- `build/cpp/opendrive_tools/odr-list-roads`
- `build/cpp/opendrive_tools/odr-list-lanes`
- `build/cpp/opendrive_tools/odr-get-xyz`
- `build/cpp/opendrive_tools/odr-validate-basic`

## Run The MCP Server

```bash
python -m opendrive_mcp.server --mcp
```

Example MCP client configuration:

```json
{
  "mcpServers": {
    "opendrive": {
      "command": "python",
      "args": ["-m", "opendrive_mcp.server", "--mcp"],
      "cwd": "/path/to/opendrive-mcp-server"
    }
  }
}
```

## Available Tools

- `summarize_map`: summarize road count, junction count, and total road length.
- `list_roads`: list road IDs, names, lengths, and junction IDs.
- `list_lanes`: list lanes for one road.
- `get_xyz`: convert `road_id`, `s`, `t`, `h` to world `x`, `y`, `z`.
- `validate_basic`: run basic parse and road/lane sanity checks.

See `docs/mcp_tools.md` for schemas and example responses.

## Command-Line Examples

```bash
python -m opendrive_mcp.server summarize_map third_party/libOpenDRIVE/tests/test.xodr
python -m opendrive_mcp.server list_roads third_party/libOpenDRIVE/tests/test.xodr
python -m opendrive_mcp.server list_lanes third_party/libOpenDRIVE/tests/test.xodr 17
python -m opendrive_mcp.server get_xyz third_party/libOpenDRIVE/tests/test.xodr 17 2.1 1.0 0.0
python -m opendrive_mcp.server validate_basic third_party/libOpenDRIVE/tests/test.xodr
```

## Backend Configuration

The default backend is `cli`.

To point the Python adapter at a custom CLI directory:

```bash
export OPENDRIVE_MCP_CLI_DIR=/path/to/opendrive-tools
```

For diagnostics only, the mock backend can be selected explicitly:

```bash
export OPENDRIVE_MCP_BACKEND=mock
```

Mock results are not accepted for real backend validation.

## Test

```bash
.venv/bin/python -m pytest
.venv/bin/python -m ruff check .
.venv/bin/python -m compileall src tests scripts
```

Local MCP acceptance with Ollama/Qwen:

```bash
export OLLAMA_MODEL=qwen2.5:7b
.venv/bin/python scripts/ollama_mcp_acceptance.py
```

See `docs/local_acceptance.md` for details.

## Documentation

- `docs/mcp_tools.md`: MCP tool schemas and examples.
- `docs/architecture.md`: high-level architecture.
- `docs/libopendrive_backend.md`: backend integration notes.
- `docs/supported_opendrive_subset.md`: supported OpenDRIVE assumptions.
- `docs/traceability.md`: trace record behavior.
- `docs/local_acceptance.md`: local Ollama/Qwen acceptance path.
- `docs/tool_admission_policy.md`: maintainer policy for adding tools.
- `CONTRIBUTING.md`: contribution and validation rules.

## License

This repository is Apache-2.0. `pageldev/libOpenDRIVE` is also Apache-2.0 licensed.