内容
# CarlaMCP
自然语言 → 可执行自动驾驶场景，在 [CARLA](https://carla.org/) 模拟器中，通过 [模型上下文协议](https://modelcontextprotocol.io/) 向任何大型语言模型（LLM）开放。
基于 [IROSA](https://arxiv.org/abs/2603.03897) 的工具架构，针对 [CARLOS](https://github.com/ika-rwth-aachen/carlos) 验证，以实现容器化部署。
像 *"在夜间大雨时，从右侧以高速公路速度进行激进的换道"* 这样的提示，变成了一个经过验证的、可重复的场景，可以在 CARLA 中运行 — 并且可以保存为规范，以便重放。
## 工作原理
```
自然语言提示 ─▶ 大型语言模型选择工具 ─▶ 验证的场景清单 ─┬─▶ 在 CARLA 中执行 ─▶ 场景结果
（Pydantic 原语） │
└─▶ 保存 .json 规范 ─▶ 重放 / 重用
```
三层，每层都可独立测试：
| 层 | 包 | 责任 |
|---|---|---|
| **原语** | `carlamcp/primitives/` | 具有面向大型语言模型的描述、范围约束和跨字段验证器的 Pydantic 模型。大型语言模型从不编写原始模拟器代码。 |
| **执行器** | `carlamcp/executors/` | 将验证的原语转换为 `carla` API 调用。唯一与实时模拟器交互的层。 |
| **服务器** | `carlamcp/server.py` | 向模型公开工具的 MCP 服务器。 |
## 项目结构
```
CarlaMCP/
├── carlamcp/
│ ├── config.py # 连接 + 模拟/生成常量
│ ├── enums.py # CARLAMap, Side, WeatherCondition
│ ├── results.py # ScenarioResult
│ ├── carla_client.py # CARLA 绑定导入 + get_client()
│ ├── world.py # 地图 / 演员 / 同步模式 / 查找 ego 辅助函数
│ ├── storage.py # 保存 / 加载场景规范（导出和重放）
│ ├── primitives/ # 每个原语一个文件 + 清单
│ │ ├── cut_in.py pedestrian.py weather.py manifest.py
│ ├── executors/ # 每个原语一个执行器 + 协调器
│ │ ├── cut_in.py pedestrian.py weather.py manifest.py
│ └── server.py # FastMCP 服务器 + 工具 + main()
├── tests/ # pytest 套件，在没有模拟器的情况下运行
│ ├── fakes.py conftest.py test_executor.py test_primitives.py
├── pyproject.toml requirements.txt .gitignore LICENSE README.md
```
## 安装
### 1. 启动 CARLA（独立终端）
```bash
~/carla/CarlaUE4.sh -RenderOffScreen -quality-level=Low &
```
### 2. 安装 CarlaMCP
```bash
cd CarlaMCP
pip install -e ".[dev]" # 包 + 测试依赖（不需要模拟器）
pip install -e ".[carla,dev]" # 还安装 carla==0.9.15 绑定
```
### 3. 验证 CARLA 连接
```bash
python -c "from carlamcp.carla_client import get_client; print(get_client().get_server_version())"
```
### 4. 运行 MCP 服务器
```bash
python -m carlamcp.server # 或：carlamcp
```
### 5. 连接到 Claude Desktop
将以下内容添加到 `claude_desktop_config.json`（使用您自己的克隆的绝对路径）：
```json
{
"mcpServers": {
"carlamcp": {
"command": "python",
"args": ["-m", "carlamcp.server"],
"cwd": "<path-to-your-CarlaMCP-clone>"
}
}
}
```
重启 Claude Desktop；CarlaMCP 工具将出现。
## 使用
连接后，与模型对话：
- *"检查 CARLA 是否正在运行"* → `get_status`
- *"在 120 km/h 下从右侧进行激进的换道，TTC 为 1.2s"* → `run_scenario`
- *"行人从 25 米外穿过，被停放的汽车遮挡，在大雾中"*
- *"将天气设置为 rain_night，强度为 0.8"* → `set_weather`
- *"验证此清单在运行前：{...}"* → `validate_scenario`
### 工具
| 工具 | 目的 |
|---|---|
| `get_status` | 检查模拟器是否可达。 |
| `list_maps` | 列出支持的城镇及其特征。 |
| `run_scenario` | 构建 + 验证 + 执行场景（可选 `save_as`）。 |
| `set_weather` | 仅应用天气预设。 |
| `validate_scenario` | 验证清单 JSON 而不运行它。 |
| `save_scenario` | 验证并持久化清单以备后用。 |
| `replay_scenario` | 加载保存的规范并执行它。 |
### 场景原语
| 原语 | 关键参数 | 默认地图 |
|---|---|---|
| `CutInManeuver` | `speed_kmh`, `ttc_s`, `side`, `ego_speed_kmh` | Town04（高速公路） |
| `PedestrianCross` | `gap_acceptance_s`, `crossing_distance_m`, `occluded` | Town03（城市） |
| `WeatherOverlay` | `condition`, `intensity` | 任意 |
### 导出和重放
任何场景都可以保存为验证的 JSON 规范，并在以后重新运行 — 可用于回归测试集、共享和场景填充 / 增强管道：
```text
run_scenario("...", cut_in_speed_kmh=120, cut_in_ttc_s=1.2, cut_in_side="right",
save_as="rainy_cutin") # 写入 scenarios/rainy_cutin.json
replay_scenario("rainy_cutin") # 重新执行完全相同的规范
```
导出层（`carlamcp/storage.py`）与执行层分离，因此生成的规范可以被下游工具在没有运行模拟器的情况下使用。参见 **路线图 → OpenSCENARIO 导出**。
## 测试
测试套件完全离线运行 — `tests/conftest.py` 注入了一个伪造的 `carla` 模块，因此执行器逻辑（生成几何、速度、排序、错误路径、碰撞指标）在没有 GPU 或运行模拟器的情况下得到验证。这使得它对 CI 友好。
```bash
pip install -e ".[dev]"
pytest -q
```
`tests/test_executor.py` 作为该项目的规范示例，使用 Google 风格的（Sphinx [Napoleon](https://sphinxcontrib-napoleon.readthedocs.io/)）文档字符串约定，该约定在每个模块中使用。
## 常见问题 — 为什么使用 Python 而不是 C++？
CARLA 在 Unreal Engine（C++）上运行，所以这是个合理的问题。对于 CarlaMCP 来说，C++ 没有带来任何好处；`carla` PyPI 包是 C++ `LibCarla` 客户端上的一个薄绑定，这里完成的所有工作（生成演员、天气、交通管理器）都完全在 Python 中公开，几乎没有这些 tick 率下的开销。只有在 *CarlaUE4 服务器构建内部* 进行的工作才值得使用 C++ — 自定义 Unreal 传感器 / 演员 / 地图资产、每帧高带宽传感器处理，其中 GIL 是瓶颈，或 C++ 场景运行器扩展。那些都不在路线图上，因此 CarlaMCP 保持纯 Python。
## 路线图
- [x] 第一阶段 — 验证的原语 + MCP 服务器 + CARLA 执行
- [x] 第二阶段 — 模块化包、离线测试套件、场景导出 / 重放
- [ ] 第三阶段 — CARLOS Docker 集成（`docker-compose.yml`）
- [ ] 第四阶段 — CSR/ISR/TCR 评估框架
- [ ] 第五阶段 — OpenSCENARIO 导出，用于 CARLOS 重放管道
- [ ] 论文 — IEEE IV / ITSC 提交
## 相关工作
- [IROSA](https://arxiv.org/abs/2603.03897) — 用于机器人技能适应的基于工具的大型语言模型架构（DLR/TUM）
- [CARLOS](https://github.com/ika-rwth-aachen/carlos) — 容器化的 CARLA 模拟框架（ika RWTH Aachen）
- [SUMO-MCP](https://arxiv.org/abs/2506.03548) — 用于交通模拟的 MCP（相邻领域）
## 许可证
[MIT](LICENSE)。
