内容
<div align="center">
<img src="docs/logo.svg" width="110" alt="加州道路 logo">
<h1>加州道路</h1>
<p><b>通过 MCP 为 AI 助手提供加利福尼亚州实时道路状况信息。</b></p>
[](https://github.com/nicglazkov/ca-roads-mcp/actions/workflows/ci.yml)
[](EVALS.md)
[](LICENSE)
[](pyproject.toml)
<p>
<a href="#添加至克劳德">添加至克劳德</a> ·
<a href="https://ca-roads-demo-15002631928.us-west1.run.app">网页演示</a> ·
<a href="#工具">工具</a> ·
<a href="#评估">评估</a> ·
<a href="#工作原理">工作原理</a>
</p>
</div>
询问“前往塔霍需要携带雪链吗？”或“17号公路现在通畅吗？”，答案来自CHP和加州交通局（Caltrans）发布的实时信息。该模型直接读取实际的调度日志，而不是根据记忆进行猜测。仅需一个连接器URL，无需账户和密钥。
没有AI助手？[网页演示](https://ca-roads-demo-15002631928.us-west1.run.app)可以在浏览器中回答相同的问题，并在地图上绘制所有内容。
<div align="center">
<img src="docs/screenshots/demo-bay-area.png" width="850"
alt="网页演示回答'现在湾区道路状况如何？'，包括判决、事件标记和道路封闭地图">
</div>
## 添加至克劳德
托管（推荐）：使用以下URL添加自定义连接器：
```
https://ca-roads-mcp-15002631928.us-west1.run.app/mcp
```
本地通过标准输入/输出：
```json
{
"mcpServers": {
"ca-roads": {
"command": "uvx",
"args": ["--from", "git+https://github.com/nicglazkov/ca-roads-mcp", "ca-roads-mcp"]
}
}
}
```
或者从检出代码：`pip install .` 然后 `ca-roads-mcp`（标准输入/输出）或 `ca-roads-mcp --transport http`（可流式传输的HTTP，监听$PORT）。
## 它了解什么
| 来源 | 数据 | 更新频率 |
|--------|------|---------|
| **CHP实时信息** | 全州事件（碰撞、危险、封闭）及调度员记录的行驶方向 | 每次请求；信息更新约1分钟/次 |
| **加州交通局道路封闭系统（LCS）** | 目前实际封闭的车道和道路，分为对通过交通的影响 | 5分钟缓存 |
| **加州交通局雪链管控** | 山区检查站的R-1/R-2/R-3要求 | 5分钟缓存 |
| **WFIGS** | 活跃的野火（名称、规模、控制情况），标记在主要高速公路10英里范围内 | 5分钟缓存 |
每个封闭记录都有一个`closure_class`，源自加州交通局的设施和封闭类型。原始信息将入口匝道维修标记为“完全封闭”，报告为封闭高速公路是不正确的，因此分类使其分开：
| closure_class | 含义 | 你可以通行吗？ |
|---|---|---|
| `full-roadway` | 道路本身在该方向封闭 | 不可以 |
| `one-way-traffic` | 单向交通，交替车道，带有旗帜 | 可以，有延误 |
| `alternating-lanes` / `moving` / `traffic-break` | 滚动或短暂施工 | 可以，轻微延误 |
| `lane` | 部分车道封闭（“4车道中的2车道封闭”） | 可以 |
| `ramp` | 一个入口匝道或连接道路封闭，道路不受影响 | 可以 |
每个响应都带有每个来源的`data_as_of`时间戳，并在信息过时或失败时提供明确的注释，以便助手可以判断答案的可信度。信息失败从不保持沉默：提供最后的有效数据，标记为过时，并附上错误信息。
## 工具
| 工具 | 回答内容 |
|------|-----------------|
| `check_route(from_place, to_place)` | 沿主要路线（17个精选路线：I-80 萨克拉门托-雷诺，US-50至塔霍，I-5，US-101，SR-17，SR-99，SR-1，I-15至拉斯维加斯，湾区高速公路，塔霍当地路线）的一切活跃事件，按路线里程排序 |
| `check_region(region)` | 整个区域（湾区，南加州，内华达山脉，中谷地，及其他4个区域）的单次调用报告：精确数量，按严重程度排序的事件，完整封闭优先，列表显示截断时间 |
| `get_incidents(highway?, area?, center?)` | 按路线、调度区或点和半径划分的实时CHP事件 |
| `get_lane_closures(route?, district?, center?)` | 目前实际封闭的车道，按上述表格分类 |
| `get_chain_controls(route?, center?)` | 当前的雪链要求；在非雪季明确表示“无活跃要求” |
| `get_wildfires(near_route?, center?)` | 附近主要高速公路的活跃火灾，附带规模和控制情况 |
`road_trip_check`提示模板向客户展示了如何为行程检查组合工具。地名在任何地方都有效：助手将城镇解析为坐标，`center`半径扫描周边所有道路，包括小道路。
## 评估
评估套件与服务器一起提供，并为每个版本设置了门控：
- **记录的固定装置**，适用于三种场景：一个内华达山脉的雪天（Twin Bridges至Meyers的R-2雪链， Emerald Bay的雪崩封闭），一个火灾封闭日（I-5在Grapevine处双向封闭），一个安静的夏天。记录模式为未来场景保存实时信息捕获。
- **85个黄金问题**，带有正确答案，包括陷阱：计划但未建立的封闭，入口匝道封闭表述为“高速公路是否封闭”，数据无法回答的预测问题。
- **评分系统**，运行克劳德对抗工具，在固定装置模式下评分，并使用LLM裁判和失败分类法（漏报条件，虚构事件，过时数据信任，错误位置）。
当前记分卡：[EVALS.md](EVALS.md)。每次发布版本时，都会在GitHub Actions上重新运行评估，并更新上面的徽章。
```sh
pip install -e ".[dev,evals]"
python evals/build_fixtures.py # 重新生成场景固定装置
python evals/run_evals.py # 需要ANTHROPIC_API_KEY
```
## 工作原理
```mermaid
flowchart LR
subgraph feeds["公共信息源"]
CHP["CHP sa.xml<br/>~1/min"]
LCS["加州交通局LCS<br/>12个区"]
CC["雪链管控<br/>9个区"]
WF["WFIGS ArcGIS"]
end
subgraph pkg["ca_roads（信息层）"]
F["异步获取<br/>TTL缓存 + 过时服务<br/>解析器"]
D["跨源去重"]
end
subgraph srv["ca_roads_mcp"]
T["6个MCP工具<br/>路线 + 区域<br/>封闭分类法"]
end
CHP & LCS & CC & WF --> F --> D --> T
T -->|"标准输入/输出 / 流式HTTP"| MCP["克劳德和MCP客户端"]
T -->|"进程内"| DEMO["网页演示<br/>(克劳德 + 地图)"]
```
三个软件包，层次清晰：
- **`ca_roads`**：信息层。无MCP依赖。异步httpx获取器，每个区TTL缓存，过时服务，上游失败时数据抢救，解析器从截断的信息中抢救完整记录（CHP在繁忙时段会截断XML记录），以及从实际运行这些信息源中学到的规则，例如将缺少的区信息视为一个空结果而不是错误。
- **`ca_roads_mcp`**：MCP表面。FastMCP服务器，精选路线和区域表格，路线名称规范化（“17”，“hwy 50”，“I80”均可），以及为LLM消费者编写的文档：数据是什么，更新频率和限制。
- **`ca_roads_demo`**：公共演示。克劳德在一个工具循环中，流式SSE与地图几何图形，硬成本上限（每个IP速率限制，每日问题上限，全球每日美元预算）。
## 开发
```sh
python -m venv .venv && . .venv/bin/activate # 或 .venv\Scripts\activate
pip install -e ".[dev]"
pytest # 118个测试，基于固定装置，无网络
ruff check .
```
文档： [部署](docs/deploy.md) · [添加数据源](docs/adding-a-source.md) · [注册提交](docs/registry.md)
## 免责声明
数据来源：CHP，加州交通局，WFIGS。 不隶属于任何机构。 状况变化比任何信息源都快； 在驾驶前请验证（511 或 [quickmap.dot.ca.gov](https://quickmap.dot.ca.gov)）。
