feat: TLBM MCP Server 初始版本

- 提供无人车运营 API 的 MCP 封装 - 支持车辆状态查询、轨迹回放、订单管理等功能 - 一键安装脚本支持快速部署 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-05-12 14:32:50 +08:00
commit 29f34fddf3
9 changed files with 1852 additions and 0 deletions
@@ -0,0 +1,137 @@
+# TLBM MCP Server
+
+TLBM 无人车运营 API 的 MCP 封装，支持 Hermes、Claude Code 等 AI Agent 直接调用运营接口。
+
+## 功能
+
+- **车辆状态查询**：实时状态、不可用统计、工作时长指标、行驶距离
+- **车辆轨迹回放**：指定日期的轨迹和状态信息
+- **订单管理**：运单汇总查询、SDK订单操作、车辆绑定
+- **用户管理**：用户注册、角色查询
+- **微信登录**：小程序登录、手机号获取
+- **内部管理**：重新聚合、状态推导（需Admin Key）
+
+## 安装
+
+### 方式一：一键安装（推荐）
+
+```bash
+curl -fsSL https://gitea.atomdancing.com/AtomDancing/tlbm-mcp/raw/branch/main/install.sh | bash
+```
+
+### 方式二：从源码安装
+
+```bash
+git clone gitea@git.atomdancing.com:AtomDancing/tlbm-mcp.git
+cd tlbm-mcp
+npm install
+npm run build
+npm link
+```
+
+## 配置
+
+### Hermes Agent
+
+在 `~/.hermes/config.yaml` 中添加：
+
+```yaml
+mcp_servers:
+  tlbm:
+    command: npx
+    args: ["-y", "tlbm-mcp"]
+    env:
+      TLBM_API_URL: "https://www.atomdancing.com/pm"
+      TLBM_ADMIN_KEY: ""  # 可选，用于内部管理接口
+```
+
+### Claude Code / Claude Desktop
+
+在 `~/.claude/settings.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "tlbm": {
+      "command": "npx",
+      "args": ["-y", "tlbm-mcp"],
+      "env": {
+        "TLBM_API_URL": "https://www.atomdancing.com/pm",
+        "TLBM_ADMIN_KEY": ""
+      }
+    }
+  }
+}
+```
+
+## 工具列表
+
+| 工具名 | 功能 |
+|--------|------|
+| `mcp_tlbm_list_vehicle_status` | 查询所有车辆最新状态 |
+| `mcp_tlbm_get_vehicle_status` | 查询指定车辆状态 |
+| `mcp_tlbm_list_vehicle_by_status` | 按状态码筛选车辆 |
+| `mcp_tlbm_get_vehicle_metrics` | 查询工作时长指标 |
+| `mcp_tlbm_get_vehicle_unavailability` | 统计不可用时长 |
+| `mcp_tlbm_list_vehicle_unavailability` | 所有车辆不可用统计 |
+| `mcp_tlbm_get_vehicle_drive_mile` | 统计行驶距离 |
+| `mcp_tlbm_get_vehicle_path_playback` | 轨迹回放 |
+| `mcp_tlbm_get_vehicle_detail` | 车辆详情（含司机） |
+| `mcp_tlbm_get_order_summary` | 查询运单汇总 |
+| `mcp_tlbm_get_today_orders` | 当日运单列表 |
+| `mcp_tlbm_get_orders_by_date` | 指定日期运单 |
+| `mcp_tlbm_get_unfinished_orders` | 未完成运单 |
+| `mcp_tlbm_get_sdk_order_list` | SDK订单列表 |
+| `mcp_tlbm_get_sdk_order_detail` | SDK订单详情 |
+| `mcp_tlbm_bind_vehicle_to_order` | 绑定车辆到订单 |
+| `mcp_tlbm_get_user_roles` | 查询用户角色 |
+| `mcp_tlbm_get_user_by_openid` | 按OpenID查询用户 |
+| `mcp_tlbm_register_user` | 注册用户 |
+| `mcp_tlbm_wx_login` | 微信小程序登录 |
+| `mcp_tlbm_wx_get_phone` | 获取微信手机号 |
+
+## 车辆状态码说明
+
+| 状态码 | 状态名称 |
+|--------|----------|
+| 0 | 关机 |
+| 1 | 开机 |
+| 2 | 任务中 |
+| 3 | 故障 |
+| 4 | 充电中 |
+| 5 | 不可接单 |
+| 6 | OTA升级中 |
+| 71 | 有任务装货开门 |
+| 72 | 有任务卸货开门 |
+| 8 | 非营运时间 |
+
+## 使用示例
+
+重启 Hermes 后，直接对话即可调用：
+
+```
+用户：查询所有车辆状态
+Hermes：[调用 mcp_tlbm_list_vehicle_status]
+        京A12345 电量85% 任务中...
+        京B67890 电量42% 充电中...
+
+用户：查看京A12345今天的轨迹
+Hermes：[调用 mcp_tlbm_get_vehicle_path_playback]
+        09:00 从起点出发...
+        10:30 到达终点...
+
+用户：有哪些未完成的订单？
+Hermes：[调用 mcp_tlbm_get_unfinished_orders]
+        OUT20260318001 运送中...
+```
+
+## 发布
+
+```bash
+npm login
+npm publish --access public
+```
+
+## License
+
+Apache-2.0