Metadata-Version: 2.5
Name: carla-traffic-mcp
Version: 0.2.7
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服务

本项目面向学生实验：学生在百炼Managed Agent中用自然语言描述交通场景，大模型编写场景业务逻辑，MCP提供版本参考、地图位置检索、经过测试的通用运行能力、静态检查和单文件组装，学生下载Python文件并在本机CARLA运行、观察和反馈。

0.2.5修复跨道路终点漏采，增加选址转路线、平滑变道、真实包围盒净距与整车通过判定；收紧传感器附着参数，服务失联时跳过重复远程清理等待。单角色方向与车道条件绑定同一连接。默认观察模式使用主窗口，不额外创建RGB相机。保留`trace_route`采样时的原始Waypoint身份，并据此匹配当前路口通行段的真实停止线，处理重叠道路和略在几何入口内侧的停止点。保留已有CARLA接口检查、天气辅助和精简交付协议：MCP返回短组装清单，百炼沙箱用同版本包确定性组装和校验，避免模型反复抄写公共骨架。通用运行辅助、多方向连接检索和完整精度道路定位继续保留，使用与部署版本一致的学生提示词。提示词核验服务版本和runtime_helpers，避免服务与提示词不配套。

场景逻辑由模型动态编写，样例不限制学生的问法或轨迹生成方式。MCP不执行模型生成的场景代码，静态检查通过不等于真实场景已运行或满足要求。

## 0.2.6 通用等待与观察

新增三个运行辅助方法，MCP仍只有三个工具；新辅助方法随单文件产物运行于学生CARLA端。源码、安装包和协议验证不等于Windows实机验收，真实课堂链路仍需独立确认。

- `ctx.spawn_waiting_vehicle(blueprint, route, ...)`：使用原生路线的真实身份，按优先距离寻找等待点。距离为偏好，不是硬下限；严格距离可传distance_tolerance_m。候选预算按同身份非路口区间分配，目标距离支持采样点间插值，仍核验实际道路；以实际车辆包围盒和可配置余量采样检查同一非路口Driving车道。找不到合法点或候选被占用时明确失败；拒绝的车辆立即回收，异常情况下仍交给运行骨架清理。普通道路可以传`reference_s`，不限定地图、路口、方向或车型。
- `ctx.observe_overview(actors=..., routes=..., locations=..., ...)`：首个step之后，按本次对象包围盒和观察范围计算固定正俯视，沿路线额外覆盖最大车身包围半径，包含转向及末端车身。显式窗口尺寸、水平FOV、边距、高度上限和可辨识像素阈值；过大范围或过小对象明确失败，不静默裁切。默认投影参数是1280×720、水平90度估计，须与实际主窗口一致；不证明遮挡或渲染效果。跟随视角继续使用已有接口。
- `ctx.inspect_actors(actors, ...)`：记录任意对象的存活、坐标和真实速度，可绘ASCII角色标签。等待辅助方法创建的车辆自动以出生位置为基线检查漂移；其他对象仅在显式给定预期位置时检查等待状态。初始落地瞬态需与持续异常区分，观测结果不等于需求验收。

等待道路采样使用最大0.5米网格，当前约束要求车身及余量在同一原生车道身份内；这是保守的几何检查，不是连续碰撞证明。上游路线不足时应调整布局或选址，不自动换路口、不绕过检查。候选尝试、采样数量均有明确上限。

测试覆盖实采Town03_Opt两路口间7.49米道路边界、任意道路方向/偏移/不同车长、候选占用/回收失败、横竖窗口和多个观察对象。该短路段是回归数据，生产算法不包含其地图/道路ID。实际课堂验收还需Windows、CARLA 0.9.12和生成后的完整场景。

## 环境与内置资料

- MCP服务端：Python 3.10及以上，不需要安装或启动CARLA。
- 学生实采基线：Windows 64位、Python 3.8.10、CARLA客户端/服务端0.9.12。输出保持Python 3.7语法兼容初筛，这不是Python 3.7实机验收结论。
- 依赖限定为CARLA客户端及工具返回的Python标准库清单，不默认接受numpy、networkx或agents。
- 随包包含11张完整采集地图的检索目录、184个实采蓝图及属性、固定0.9.12提交的API参考。
- 地图包括Town01、Town02、Town04、Town05、Town10HD的普通版与_Opt，以及Town03_Opt。普通Town03在采集环境加载异常，未纳入可生成目标地图。

目录包含2,868条候选记录，其中18条环岛通行记录。它们来自实际采集和明确的几何推导，不是2,868个独立路口，也不保证任意自然语言要求都有匹配。

## 三个工具

| 工具 | 功能 |
|---|---|
| `get_carla_context` | 返回版本、依赖、代码契约，以及按topic选择的API和资源参考 |
| `find_scene_location` | 依据道路条件检索随包目录，返回定位、路线提示和证据；不自动放宽要求 |
| `build_python_file` | 首选prepare返回摘要清单；兼容assemble和旧文本摘要校验 |

参考查询：

```json
{"topics":["maps","actors","control"]}
```

需要蓝图时可加入`resource:vehicle.*`、`resource:vehicle.tesla.model3`或`resource:static.prop.*barrier*`。每个模式最多返回20项，截断后应缩小范围。需要类方法参数时，可加入`api:carla.Map`或`api:carla.Vehicle`等，每次最多返回20类。

## 地图检索

默认读取包内目录，无需教师或学生上传地图索引，也无需设置`CARLA_MAP_CATALOG`。需要测试其他同格式目录时可以设置该变量覆盖。

支持的条件：

- `junction_type`：`any`、`road`、`T`、`cross`、`roundabout`、`multi_way`。
- `turn`：`any`、`left`、`right`、`straight`。
- `signal_required`：布尔值。
- `min_exit_lanes`、`max_exit_lanes`：出口车道数量范围。
- `min_exit_length_m`：目录中连续出口段的最小长度。
- `lane_change`：`any`、`left`、`right`、`either`。
- `map`、`junction_id`：按明确地图或路口查询；学生一般不需要填写。
- `exclude_junction_ids`、`exclude_location_ids`：换址时排除已用位置。
- `limit`：返回1至10条候选，默认3条。
- `movements`：同一路口1至16条连接要求，每项包含`entry_from`或`exit_to`，可带`turn`和`role`；这不是车辆数量限制。方向采用世界+X东、-Y北。返回`movement_matches`逐条保留真实定位和证据；顶层条件仅筛选锚点连接。

例如：

```json
{"requirements":{"junction_type":"T","turn":"right","min_exit_lanes":2,"lane_change":"left"}}
```

`matched`返回候选及证据；`no_match_in_index`返回未满足条件和备选建议，备选不能当作已经匹配；`unsupported_condition`表示条件没有结构化查询依据；`invalid_request`表示参数或要求冲突；`catalog_error`表示目录读取异常。无匹配不等于所有官方地图都不存在该场景。

同一物理路口的普通版与_Opt会去重。`route_hint`是稀疏定位/路径提示，模型仍需在本机查询waypoint、核验车道并编写连续路线及控制逻辑。

## 生成程序契约

模型提交以下函数及必要辅助代码：

```python
def setup_scene(ctx):
    pass


def step_scene(ctx, elapsed_seconds, frame_index):
    return False
```

公共骨架负责连接、地图加载、同步主循环、观察更新和清理。创建对象用`ctx.spawn_actor`，其他方式创建后立即`ctx.register_actor`；状态保存到`ctx.state`。恢复操作通过`ctx.restore_after_run`登记。

`get_carla_context.runtime_helpers`直接从随包源码提取公开方法签名与说明。优先使用`waypoint`将真实定位记录转为CARLA路点、`spawn_vehicle`的有限同路线候选、`trace_route`的连续路径和准确出口检查、`route_progress`的实际进度、`drive_route`的跟踪与末端停车、`conflict_region`的路径几何参考以及`set_traffic_lights`的先登记恢复后修改。模型仍决定角色、动作、事件条件和参数，可生成特殊算法。辅助源码在组装时直接嵌入完整脚本，学生本机不需要安装MCP包。

定位记录的`s`保留实采原始精度，不四舍五入。`waypoint`对旧记录的小误差只允许恢复同道路、车道且位置/方向匹配的真实端点，歧义或超差明确失败。`trace_route`默认严格满足前后延伸长度；自动布局可显式设置`allow_shorter=True`，在分支或道路末端前停止延伸并返回实际长度，路口内部路径仍须完整。学生指定精确距离时保留严格模式。

`trace_route`同时返回`waypoint_provenance`，逐点保留原始`road_id`、`section_id`、`lane_id`、道路`s`和路口身份，与`points`严格一一对齐。需要选灯时直接使用这份原始路线，保留`points`、`distances`、`waypoint_provenance`及`junction_start/junction_end`的对应关系；不要单独切片、重排或重采样其中一项，也不要用`make_route(route['points'])`重建后丢掉身份。改变路线时重新调用`trace_route`。模型不应通过`Map.get_waypoint`按几何坐标反推道路身份，因为重叠道路上的投影可能落在另一条道路。

使用`ctx.follow_actor(actor, distance=8, height=5, pitch=-20)`设置主窗口跟随，或用`ctx.observe(location, height=30, yaw=0, pitch=-75)`设置俯视。每帧函数必须有界、非阻塞，不自行tick、切图或建立主循环。

生成脚本支持`--help`、`--check`、`--host`、`--port`、`--duration`、`--timeout`和`--realtime`。`--realtime`按墙钟限速，保持0.05秒同步步长；`--check`只读核对连接、版本和地图可用性，不创建场景；`--timeout`限制单次CARLA通信等待，不会强行中断模型回调内的无限循环。

## 0.2.5生成检查与运行辅助

- 已知CARLA调用验证可确认的构造/方法签名、必需/重复/过多参数、确定字面量类型与非有限数值；保守识别简单别名、绑定方法和明确的CARLA返回类型。
- 已知CARLA调用的未知`*args/**kwargs`、动态`getattr`、无可核验构造签名的直接构造，返回`needs_fix`要求显式改写。普通未知Python对象和动态标量不声称全部推断；这不是Python安全沙箱。
- ctx公开辅助方法必须直接`ctx.method(...)`调用；宽泛`Exception`、裸except、API类型/属性错误不能被静默吞掉，应记录原始上下文后重新raise，或捕获明确的预期运行异常进行有限处理。
- `ctx.set_weather(...)`支持0.9.12的13个全名字段，校验类型、有限值及官方给定范围。`None`保留原值，公共骨架恢复原天气。
- `ctx.traffic_lights_for_route(route)`使用`trace_route`保留的原始Waypoint身份，先核对真实停止路点的道路、section、车道和道路`s`区间，再核对几何、方向与停止位置歧义，返回`traffic_lights`、`stop_s`、`stop_location`和`evidence`。范围从入口前指定距离到本次`junction_end`，允许属于当前通行段且略在几何入口内侧的真实停止线，排除`after`段和下一个路口；不能自行要求停止线必须在`entry_s`之前。`stop_s`使用`route['distances']`的累计距离坐标，`evidence.road_s`才是道路`s`。模型直接调用此助手，不手写Map坐标反推或用入口/灯杆位置猜停止线；无匹配返回空，歧义和RPC错误明确失败。
- `DURATION_SECONDS`可声明为大于0且不超过600的数字字面量；清单、默认运行时长和运行命令保持一致，显式`--duration`仍可覆盖。缺省兼容30秒。没有修改学生的一键运行器。

静态检查和文件摘要不代表每个生成场景已在CARLA运行。具体路线、障碍物几何、车辆响应及画面仍须本机验收；版本验收区分工具单测、正式包安装与实机接口证据。

## 从源码启动

```bash
uv run carla-traffic-mcp
```

默认stdio协议，启动后等待MCP客户端请求。安装时显式固定版本：

```bash
uvx --from carla-traffic-mcp==0.2.5 carla-traffic-mcp
```

部署前确认所选版本已经在PyPI发布；正式课程版本和云端部署结果以本次发布记录及课程参数单为准。

## 标准百炼托管配置与开发诊断

课堂发布门槛是学生按手册复制标准uvx配置后可直接部署并调用MCP，不要求学生进入函数计算控制台修改启动参数。

使用标准uvx托管配置；云端的已部署版本与工具调用结果以具体服务验收记录为准。开发诊断不作为学生操作步骤，发布PyPI后不会自动更新既有云端服务。

## 百炼Managed Agent文件交付

0.2.5首选`prepare`，与旧`assemble`、`verify_written`兼容。新版提示词必须与新版MCP配套，不能只改一边。公开工具仍为三个，不增加学生本机依赖。

1. 模型通过`write`保存业务代码到`/mnt/session/scene_logic.py`，再把相同业务代码提交`build_python_file(mode="prepare", source=..., scenario_name=..., target_map=...)`。
2. MCP静态检查并使用公共组装函数计算最终产物，返回小型JSON清单，包含`schema_version`、`package_version`、场景名称、目标地图、业务源码摘要/长度和完整产物摘要/长度。不会返回完整源码，也不依赖FC临时目录。
3. 将原始清单保存为`/mnt/session/build_plan.json`；百炼沙箱用同版本PyPI包的`carla_mcp.delivery`读取业务源码并自动拼装公共骨架。仅安装主包即可，生成命令没有MCP第三方依赖。
4. 命令从实际文件字节计算摘要；源码、版本或完整产物与原清单不一致就失败，拒绝交付。成功输出短JSON，直接`mark_artifacts`登记完整`.py`，不再回读完整源码、不再向MCP全文校验。
5. 学生从产物区下载单个`scenario.py`。内部业务文件和清单不交给学生拼接；Files API下载仍需核对真实文件摘要。静态通过与文件一致不证明CARLA场景效果通过。

部署版本正式发布后，在百炼文件环境中首次使用时执行（后续同会话复用）：

```bash
python3 -m pip install --disable-pip-version-check --no-deps --only-binary=:all: --target /mnt/session/.carla-builder/0.2.5 --index-url https://pypi.org/simple --timeout 20 --retries 1 carla-traffic-mcp==0.2.5
mkdir -p /mnt/session/outputs
PYTHONPATH=/mnt/session/.carla-builder/0.2.5 python3 -m carla_mcp.delivery --source /mnt/session/scene_logic.py --manifest /mnt/session/build_plan.json --output /mnt/session/outputs/scenario.py
```

已有输出默认不覆盖；有明确替换需要时添加`--overwrite`，通过所有摘要检查后才原子替换。业务源码仅规范化为`source.strip() + "\n"`，内部字符和换行不会被自动改写。安装/连接错误最多重试一次，禁止按SHA暴力枚举字节来猜测原稿。

仅百炼沙箱的组装命令需要Python>=3.10；学生本机仍为课程Python3.8.10。MCP与沙箱不共享文件系统，不能把FC产物路径当成沙箱文件或下载地址。默认不增加OSS或下载服务。

MCP是生成前置条件；未取得真实`prepare`成功清单不能绕过工具直接登记文件。旧`assemble`若仍使用，应在沙箱本地核对实际字节与原始SHA，避免无意义的全文回传。`/artifacts/{id}`仅HTTP部署模式暴露，stdio不能直接用于下载。

官方依据：[Managed Agents内置工具](https://help.aliyun.com/zh/model-studio/managed-agents-builtin-tools)、[Managed Agent文件上传与挂载](https://docs.bailian.console.aliyun.com/zh/model-studio/managed-agents-file)。

## 本地HTTP模式

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

MCP端点为`http://127.0.0.1:8000/mcp`。可在真实服务地址后拼接工具返回的`download_path`下载；该路由与百炼原生文件工具链路不同，stdio部署不会直接暴露HTTP下载端点。

## 验证范围与兼容

检查器可以拦截可确定的错误API、枚举、命名参数、蓝图ID和不可修改属性，但不推断所有动态类型，不完整验证物理效果或路线行为。完整课堂验收还应覆盖真实模型、百炼文件工具和Windows CARLA。

本地开发与测试方法见`LOCAL_TESTING.md`。0.1.x模板入口保留为`carla-traffic-mcp-legacy`；新版默认入口只暴露上述三个工具。

## 许可证

MIT。随包保留CARLA上游API资料的许可说明。

## 0.2.7：公共返回结构

部署状态以发布验收记录为准。三个MCP工具及运行辅助函数签名保持不变；运行骨架和几何算法未改。`geometry_result_contract`中obstacle_clearance、actor_passed_route_point和observe_overview现在明确使用type/fields/example/note结构，runtime_helpers提供对应返回类型和合同路径。旧版前两个项目是字段名数组，不能再把它误解成结果按位置排列。

公共静态检查增加返回值检查：直接ctx调用、顺序块中单次赋值及可确定的简单别名；检查已知字典数字下标及logging/百分号数值格式误用已知列表或字典。变量重新赋值、可变别名、参数逃逸、嵌套作用域、复杂控制流和跨函数传播等不作全面推断；不是Python完整类型检查器，不声称所有动态错误都能发现。正常列表、数字键字典、列表记录取字段及%s输出继续允许。

源码、MCP远程prepare和工作区deliver_file共用检查规则。新版本包不能混用旧版本清单；正式启用前须另行发布并同步MCP与工作区版本。此修改不证明场景物理行为或Windows实机通过。
