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默认安装资源。

新版工具

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

安装与启动

显式固定候选版本：

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

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

百炼脚本部署配置

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

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

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