Metadata-Version: 2.5
Name: carla-traffic-mcp
Version: 0.2.0rc1
Summary: CARLA Traffic Scenario MCP Server for Bailian Platform
Author-email: NextLearn <chenlx2023@gmail.com>
License: MIT
Keywords: autonomous-driving,carla,mcp,simulation,traffic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: mcp==1.26.0
Description-Content-Type: text/markdown

# CARLA交通场景MCP服务

`carla-traffic-mcp 0.2.0rc1` 是用于学生实验的平台联调候选版。大模型根据自然语言编写场景逻辑，MCP提供参考、地图目录检索、静态检查和Python文件组装，学生在本机CARLA中运行并观察效果。

本候选尚未完成百炼真实模型联调、Windows客户端与CARLA实机验收。默认不附带真实地图目录，不能直接作为完整课堂服务使用。

## 环境与分工

- 云端MCP服务需要Python 3.10及以上，不需要安装或运行CARLA。
- 输出脚本面向CARLA 0.9.12，采用Python 3.7语法初筛。
- 学生提前准备Windows、CARLA及匹配的Python客户端；云端服务不会安装学生的本机环境。
- 地图与构件限定为课程指定的CARLA默认安装资源。

## 新版工具

| 工具 | 用途 |
|---|---|
| `get_carla_context` | 获取版本、允许模块、代码接口和生成约定 |
| `find_scene_location` | 按结构化道路条件检索已采集的地图目录 |
| `build_python_file` | 静态检查、组装单个Python文件，并校验回传文本 |

具体场景算法由大模型编写。公共骨架负责连接、地图加载、同步循环和对象清理。MCP不执行模型生成的场景代码，不自动评价仿真效果。

## 安装与启动

显式固定候选版本：

```bash
uvx --from carla-traffic-mcp==0.2.0rc1 carla-traffic-mcp
```

默认使用stdio协议，启动后等待MCP客户端请求，不是供用户输入文字的命令行程序。

## 百炼脚本部署配置

在百炼创建自定义MCP服务，选择脚本部署、uvx安装方式，粘贴：

```json
{
  "mcpServers": {
    "carla-student-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "carla-traffic-mcp==0.2.0rc1", "carla-traffic-mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "PYTHONUNBUFFERED": "1",
        "CARLA_ARTIFACT_DIR": "/tmp/carla-traffic-mcp/artifacts"
      }
    }
  }
}
```

该配置用于平台联调，不包含真实地图目录。智能体需另行启用文件工具write、read、download_file，写入返回的完整source并导出文件。stdio部署不直接暴露本服务的HTTP下载路由。

产物保存于服务本地文件系统。实例重启或请求分配到其他实例时，后续文本校验可能找不到原始产物；百炼联调需验证这一行为，不能把/tmp视作跨实例持久存储。

## 地图目录

部署方需在匹配的CARLA环境采集、验证目录，并将服务可读取的JSON路径配置为`CARLA_MAP_CATALOG`。不能使用开发者电脑路径代替云端文件路径。

当前支持`junction_type`、`turn`、`signal_required`、`min_exit_lanes`和`min_exit_length_m`。未配置目录时返回`catalog_not_ready`；不支持的条件返回`unsupported_condition`；目录内无匹配时返回`no_match_in_index`。测试夹具不是真实地图数据。

真实目录采集、随部署分发和更广泛的检索能力仍待完成。

## 本地HTTP测试

```bash
MCP_TRANSPORT=streamable-http HOST=127.0.0.1 PORT=8000 carla-traffic-mcp
```

MCP端点为`http://127.0.0.1:8000/mcp`。该模式可通过工具返回的`download_path`下载文件；它与百炼内置文件工具的交付链路不同。

## 验证边界

静态检查不是安全沙箱，也不能完整验证CARLA API、路径规划或物理效果。`verify_written`仅比对服务收到的文本与原始产物，真实下载内容仍需验收。

测试通过真实MCP协议调用和本机HTTP下载检查工具链，CARLA生命周期使用模拟对象；不等同于真实模型生成或3D仿真验收。详见随源码包提供的`LOCAL_TESTING.md`。

## 旧版兼容

0.1.x的模板工具保留在`carla-traffic-mcp-legacy`入口。新版默认命令只暴露上述三个工具，原有智能体如需保持原行为，应继续固定使用原版本。

## 许可证

MIT
