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

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:

git submodule update --init --recursive

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

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

Build the libOpenDRIVE-backed CLI tools:

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

python -m opendrive_mcp.server --mcp

Example MCP client configuration:

{
  "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

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:

export OPENDRIVE_MCP_CLI_DIR=/path/to/opendrive-tools

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

export OPENDRIVE_MCP_BACKEND=mock

Mock results are not accepted for real backend validation.

Test

.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:

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.