connected-car-mcp

一个基于合成联网车队的 MCP（模型上下文协议）服务器：遥测、基于规则的异常检测和维护建议，以五个窄工具而非一个开放式查询接口的形式暴露。

作为一个小型、自包含的示例，用于说明一种特定的设计习惯：决定什么应该放在工具边界之后，并记录跨越该边界的每次调用。完全在本地生成的合成数据上运行——无需外部 API、无需账户、无需专有来源。

为什么这样设计

整个数据集可以通过一个单一的 run_query(sql: str) 工具暴露。这对于代理（agent）可靠调用来说是错误的形态：它在调用时将模式学习推给模型，并且无法按能力范围界定或审计“可以询问什么”。相反：

模型组合这些工具——摘要 → 选择标记的车辆 → 拉取其遥测数据 → 获取建议——而不是对原始行编写自由形式的查询。这也使审计变得简单：只有五个定义明确的调用需要记录，因此 audit_log.jsonl（参见 connected_car_mcp/audit.py）每次调用一行——时间戳、工具、参数、持续时间、成功/失败——无需每个工具的自定义逻辑。生产部署将通过 MCPServer 的 middleware 钩子（该钩子能看到每个 JSON-RPC 调用、工具或资源）以结构化日志形式发出相同记录，而不是本地文件；这里的装饰器使演示无需额外基础设施即可运行。

异常阈值简单且可解释（engine_temp_c >= 110，而非训练模型）是有意为之——车队监控器的标志需要能被人类审计，而不仅仅是准确。

Related MCP server: mcp-live-telemetry

数据

data/generate_telemetry.py 生成一个确定性（固定种子）、完全合成的数据集：12 辆车，每 10 分钟一次读数，持续 3 天。少数车辆被预置了故障，以便异常检测器有真实的信号可找：

• CCV-004 — 发动机温度进入临界范围（冷却系统故障）

• CCV-009 — 电池电压随时间下降（电池/发电机故障）

• CCV-002、CCV-011 — 间歇性 DTC 故障码

• CCV-006 — 偶尔的激烈驾驶速度尖峰

data/telemetry.csv 已提交，因此仓库可以立即运行；使用以下命令重新生成：

python data/generate_telemetry.py

运行

python -m venv .venv
.venv/Scripts/activate        # .venv/bin/activate on macOS/Linux
pip install -r requirements.txt

python -m connected_car_mcp.server   # starts the MCP server over stdio

要从 Claude Desktop 或其他 MCP 客户端尝试，请将 cwd 设置为仓库根目录，指向该模块，例如在 claude_desktop_config.json 中：

{
  "mcpServers": {
    "connected-car-fleet": {
      "command": "python",
      "args": ["-m", "connected_car_mcp.server"],
      "cwd": "/path/to/connected-car-mcp"
    }
  }
}

然后询问类似 “车队中哪些车辆现在需要关注，为什么？” — 模型将调用 fleet_health_summary，对标记的车辆跟进 detect_anomalies，并可以调用 get_maintenance_recommendations 将其转化为后续行动。

测试

pip install pytest
pytest tests/

直接覆盖数据层（车队规模、未知车辆处理，以及预置故障确实被标记），而不是通过 MCP 协议层进行往返测试。

项目结构

connected_car_mcp/
  server.py       MCP tool + resource definitions
  data_store.py   Query layer over the telemetry CSV (pandas)
  audit.py        Per-call audit log decorator
data/
  generate_telemetry.py   Synthetic dataset generator
  telemetry.csv            Generated dataset (committed)
tests/
  test_data_store.py

许可证

MIT — 参见 LICENSE。