tlbm-mcp/README.md

# TLBM MCP Server

TLBM 无人车运营 API 的 MCP 封装，支持 Hermes、Claude Code 等 AI Agent 直接调用运营接口。

## 功能

- **车辆状态查询**：实时状态、不可用统计、工作时长指标、行驶距离
- **车辆轨迹回放**：指定日期的轨迹和状态信息
- **订单管理**：运单汇总查询、SDK订单操作、车辆绑定
- **用户管理**：用户注册、角色查询
- **微信登录**：小程序登录、手机号获取
- **内部管理**：重新聚合、状态推导（需Admin Key）

## 安装

### 方式一：一键安装（推荐）

公开仓库：
```bash
curl -fsSL https://git.atomdancing.com/AtomDancing/tlbm-mcp/raw/branch/main/install.sh | bash
```

私有仓库（需要 Token）：
```bash
curl -fsSL https://git.atomdancing.com/AtomDancing/tlbm-mcp/raw/branch/main/install.sh | bash -s -- --token=YOUR_TOKEN
```

> **获取 Token**：Gitea -> 设置 -> 应用 -> 生成访问令牌

### 方式二：从源码安装

公开仓库：
```bash
git clone https://git.atomdancing.com/AtomDancing/tlbm-mcp.git
cd tlbm-mcp
npm install
npm run build
npm link
```

私有仓库（需要 Token）：
```bash
git clone https://oauth2:YOUR_TOKEN@git.atomdancing.com/AtomDancing/tlbm-mcp.git
cd tlbm-mcp
npm install
npm run build
npm link
```

## 更新

### 一键更新

重新运行安装脚本即可更新：

```bash
curl -fsSL https://git.atomdancing.com/AtomDancing/tlbm-mcp/raw/branch/main/install.sh | bash
```

私有仓库：
```bash
curl -fsSL https://git.atomdancing.com/AtomDancing/tlbm-mcp/raw/branch/main/install.sh | bash -s -- --token=YOUR_TOKEN
```

### 手动更新

```bash
cd tlbm-mcp
git pull
npm install
npm run build
```

> **注意**：更新后需重启 MCP 客户端（Hermes / Claude Code）才能生效。

## 配置

### 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