Metadata-Version: 2.5
Name: carla-traffic-mcp
Version: 0.2.0
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运行、观察和反馈。

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

## 环境与内置资料

- 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` | 静态检查与单文件组装，或校验回传文本与指定SHA-256是否一致 |

参考查询：

```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条。

例如：

```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`登记。

使用`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`。`--check`只读核对连接、版本和地图可用性，不创建场景；`--timeout`限制单次CARLA通信等待，不会强行中断模型回调内的无限循环。

## 从源码启动

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

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

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

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

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

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

开发联调中已观察到stdio子命令经过托管层后可能被拆分。命令模式和数组模式均进行过排查，尚不能据此断言某种FC手工配置已经解决实际云端问题。有关实参、进程和握手诊断应保存在发布验收记录，不作为学生操作步骤。正式部署配置需经标准路径复验后发放。

## 百炼Managed Agent文件交付

本课程使用Managed Agent的`write`、`read`和`mark_artifacts`。配置中应显式启用write和read，mark_artifacts由平台运行时提供并返回真实`file_id`。产物通过控制台会话产物区或Files API获取，不再配置已下线的download_file。

MCP是生成前置条件：会话必须实际可调用三个课程工具。工具未挂载或首次参考调用因服务故障失败时，应停止生成与文件交付，提示修复服务；不能让模型用bash、记忆或write绕过检查交付替代程序。

1. 模型调用`build_python_file(mode="assemble")`，保留返回的完整`source`和`sha256`。
2. 用`write`原样写入文件，再用`read`回读实际文件文本。
3. 调用`build_python_file(mode="verify_written", source=回读文本, expected_sha256=assemble原始sha256)`。
4. 返回`verified`后，用`mark_artifacts`登记实际.py文件，保存平台返回的`file_id`。
5. 控制台用户从会话产物区下载；API客户端依据`file_id`调用Files API取回文件。没有平台提供的下载URL时，不把file_id或沙箱路径编造成链接。

摘要模式不依赖跨函数计算实例的本地文件状态。它只证明收到的文本与调用方给定摘要一致，不证明摘要来自可信原始产物、沙箱文件确实被读取或最终下载字节一致；平台联调必须另核对真实下载。

保留`artifact_id`的旧校验方式依赖同一文件系统，在百炼跨实例调用中不宜作为默认链路。`/tmp`不是跨实例持久存储。

MCP包仍采用PyPI发布和uvx托管。Managed Agent如何连接该托管服务，应以实际联调确认的接入配置为准；本文不把旧FlowAgent界面入口当作Managed Agent的操作步骤。

官方依据：[Managed Agents内置工具](https://help.aliyun.com/zh/model-studio/managed-agents-builtin-tools)、[Managed Agent产物取回示例](https://docs.agent.bailian.aliyun.com/zh/managed-agents/best-practices/data-analysis)。

## 本地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资料的许可说明。
