hhz/tlbm-mcp
1
0
Fork 0
forked from AtomDancing/tlbm-mcp
Code Pull Requests Activity

feat: TLBM MCP Server 初始版本

Browse Source 
- 提供无人车运营 API 的 MCP 封装
- 支持车辆状态查询、轨迹回放、订单管理等功能
- 一键安装脚本支持快速部署

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
wangjun
2026-05-12 14:32:50 +08:00
co-authored by Claude Opus 4.6
commit 29f34fddf3
9 changed files with 1852 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+5
View File
@@ -0,0 +1,5 @@
node_modules/
dist/
.idea/
*.log
.DS_Store
README.md
+137
View File
@@ -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
config-claude.json
+12
View File
@@ -0,0 +1,12 @@
{
"mcpServers": {
"tlbm": {
"command": "npx",
"args": ["-y", "tlbm-mcp"],
"env": {
"TLBM_API_URL": "https://www.atomdancing.com/pm",
"TLBM_ADMIN_KEY": ""
}
}
}
}
config-hermes.yaml
+12
View File
@@ -0,0 +1,12 @@
# Hermes Agent 配置片段
# 复制到 ~/.hermes/config.yaml 的 mcp_servers 部分
mcp_servers:
tlbm:
command: npx
args:
- -y
- tlbm-mcp
env:
TLBM_API_URL: https://www.atomdancing.com/pm
TLBM_ADMIN_KEY: "" # 可选，用于内部管理接口
install.sh
Executable
+49
View File
@@ -0,0 +1,49 @@
#!/bin/bash
set -e
echo "🚀 TLBM MCP 一键安装脚本"
# 检测是否已克隆
if [ -d "tlbm-mcp" ]; then
echo "📁 检测到已存在 tlbm-mcp 目录"
cd tlbm-mcp
git pull
else
echo "📥 克隆仓库..."
git clone gitea@git.atomdancing.com:AtomDancing/tlbm-mcp.git
cd tlbm-mcp
fi
echo "📦 安装依赖..."
npm install
echo "🔨 构建项目..."
npm run build
echo "🔗 链接到全局..."
npm link
echo "✅ 安装完成！"
echo ""
echo "接下来请配置 MCP 客户端："
echo ""
echo "Hermes Agent (~/.hermes/config.yaml):"
echo ' mcp_servers:
tlbm:
command: npx
args: ["-y", "tlbm-mcp"]
env:
TLBM_API_URL: "https://www.atomdancing.com/pm"
TLBM_ADMIN_KEY: ""'
echo ""
echo "Claude Code (~/.claude/settings.json):"
echo ' "mcpServers": {
"tlbm": {
"command": "npx",
"args": ["-y", "tlbm-mcp"],
"env": {
"TLBM_API_URL": "https://www.atomdancing.com/pm",
"TLBM_ADMIN_KEY": ""
}
}
}'
package-lock.json
Generated
+1177
View File
File diff suppressed because it is too large Load Diff
package.json
+24
View File
@@ -0,0 +1,24 @@
{
"name": "tlbm-mcp",
"version": "1.0.0",
"description": "TLBM 无人车运营 API MCP Server",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"bin": {
"tlbm-mcp": "dist/index.js"
},
"scripts": {
"build": "tsc",
"start": "node dist/index.js"
},
"keywords": ["mcp", "vehicle", "delivery", "autonomous"],
"author": "AtomDancing",
"license": "Apache-2.0",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.0.0"
},
"devDependencies": {
"@types/node": "^20.0.0",
"typescript": "^5.0.0"
}
}
src/index.ts
+420
View File
@@ -0,0 +1,420 @@
#!/usr/bin/env node
/**
* TLBM MCP Server - 无人车运营 API MCP 封装
*
* 基于 http://localhost:8080/v3/api-docs 的 OpenAPI 规范自动生成
* 线上服务地址: https://www.atomdancing.com/pm
*/
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
// API 配置
const API_BASE_URL = process.env.TLBM_API_URL || "https://www.atomdancing.com/pm";
const ADMIN_KEY = process.env.TLBM_ADMIN_KEY || "";
// HTTP 请求函数
async function httpRequest(method: string, path: string, params?: Record<string, any>, body?: any, headers?: Record<string, string>): Promise<any> {
const url = new URL(`${API_BASE_URL}${path}`);
// 添加查询参数
if (params && method === "GET") {
Object.entries(params).forEach(([key, value]) => {
if (value !== undefined && value !== null) {
url.searchParams.append(key, String(value));
}
});
}
const fetchHeaders: Record<string, string> = {
"Content-Type": "application/json",
...headers,
};
if (ADMIN_KEY && path.startsWith("/api/admin")) {
fetchHeaders["X-Admin-Key"] = ADMIN_KEY;
}
const response = await fetch(url.toString(), {
method,
headers: fetchHeaders,
body: body ? JSON.stringify(body) : undefined,
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}
return response.json();
}
// 工具定义
const TOOLS = [
// === 车辆状态 ===
{
name: "list_vehicle_status",
description: "查询所有车辆最新状态，按电量由低到高排序",
inputSchema: { type: "object", properties: {} },
endpoint: { method: "GET", path: "/api/vehicle/status/list" },
},
{
name: "get_vehicle_status",
description: "根据车牌号查询车辆最新状态",
inputSchema: {
type: "object",
properties: {
vinId: { type: "string", description: "车牌号，如：京A12345" },
},
required: ["vinId"],
},
endpoint: { method: "GET", path: "/api/vehicle/status/getByVinId" },
},
{
name: "list_vehicle_by_status",
description: "根据状态码查询车辆列表",
inputSchema: {
type: "object",
properties: {
status: { type: "integer", description: "车辆状态码：0=关机,1=开机,2=任务中,3=故障,4=充电中,5=不可接单,6=OTA升级中,71=有任务装货开门,72=有任务卸货开门,8=非营运时间" },
},
required: ["status"],
},
endpoint: { method: "GET", path: "/api/vehicle/status/listByStatus" },
},
{
name: "get_vehicle_metrics",
description: "获取指定车辆的工作时长等指标（工作时间窗口9:00-16:00）",
inputSchema: {
type: "object",
properties: {
vinId: { type: "string", description: "车牌号" },
date: { type: "string", description: "日期 yyyy-MM-dd，默认当天" },
},
required: ["vinId"],
},
endpoint: { method: "GET", path: "/api/vehicle/status/metrics" },
},
{
name: "get_vehicle_unavailability",
description: "统计车辆不可用时长（关机、故障、充电、低电量等）",
inputSchema: {
type: "object",
properties: {
vinId: { type: "string", description: "车牌号" },
date: { type: "string", description: "日期 yyyy-MM-dd，默认当天" },
},
required: ["vinId"],
},
endpoint: { method: "GET", path: "/api/vehicle/status/unavailability" },
},
{
name: "list_vehicle_unavailability",
description: "统计所有车辆不可用时长，按不可用时长从小到大排序",
inputSchema: {
type: "object",
properties: {
date: { type: "string", description: "日期 yyyy-MM-dd，默认当天" },
},
},
endpoint: { method: "GET", path: "/api/vehicle/status/unavailability/list" },
},
{
name: "get_vehicle_drive_mile",
description: "统计车辆在任务中和非任务中的行驶距离",
inputSchema: {
type: "object",
properties: {
vinId: { type: "string", description: "车牌号（可选，不传则查询所有车辆）" },
date: { type: "string", description: "日期 yyyy-MM-dd，默认当天" },
},
},
endpoint: { method: "GET", path: "/api/vehicle/status/driveMile" },
},
// === 车辆操作 ===
{
name: "get_vehicle_path_playback",
description: "车辆运行轨迹回放，获取指定日期的轨迹和状态信息",
inputSchema: {
type: "object",
properties: {
vinId: { type: "string", description: "车牌号" },
date: { type: "string", description: "日期 yyyy-MM-dd" },
status: { type: "integer", description: "状态码（可选）" },
},
required: ["vinId", "date"],
},
endpoint: { method: "GET", path: "/api/vehicle/path/playback" },
},
{
name: "get_vehicle_detail",
description: "获取车辆详细信息（含司机信息）",
inputSchema: {
type: "object",
properties: {
vinId: { type: "string", description: "车牌号" },
},
required: ["vinId"],
},
endpoint: { method: "GET", path: "/api/rpc/vehicle/detail/{vinId}" },
},
// === 订单管理 ===
{
name: "get_order_summary",
description: "根据外部订单号查询运单汇总信息",
inputSchema: {
type: "object",
properties: {
outOrderNo: { type: "string", description: "外部订单号" },
},
required: ["outOrderNo"],
},
endpoint: { method: "GET", path: "/api/order/summary/{outOrderNo}" },
},
{
name: "get_today_orders",
description: "查询当日运单汇总列表",
inputSchema: { type: "object", properties: {} },
endpoint: { method: "GET", path: "/api/order/summary/today" },
},
{
name: "get_orders_by_date",
description: "查询指定日期的运单汇总列表",
inputSchema: {
type: "object",
properties: {
date: { type: "string", description: "日期 yyyy-MM-dd" },
},
required: ["date"],
},
endpoint: { method: "GET", path: "/api/order/summary/date" },
},
{
name: "get_unfinished_orders",
description: "查询所有未完成的运单汇总列表",
inputSchema: { type: "object", properties: {} },
endpoint: { method: "GET", path: "/api/order/summary/unfinished" },
},
{
name: "get_sdk_order_list",
description: "SDK查询订单列表，支持分页和状态筛选",
inputSchema: {
type: "object",
properties: {
userId: { type: "integer", description: "用户ID" },
orderStatus: { type: "string", enum: ["IN_PROGRESS", "COMPLETED"], description: "订单状态：IN_PROGRESS=进行中，COMPLETED=已完成" },
pageNum: { type: "integer", default: 1, description: "页码" },
pageSize: { type: "integer", default: 10, description: "每页大小" },
},
},
endpoint: { method: "GET", path: "/api/order/sdk/list" },
},
{
name: "get_sdk_order_detail",
description: "SDK查询订单详情",
inputSchema: {
type: "object",
properties: {
orderId: { type: "string", description: "订单号" },
},
required: ["orderId"],
},
endpoint: { method: "GET", path: "/api/order/sdk/detail/{orderId}" },
},
{
name: "bind_vehicle_to_order",
description: "绑定车辆到订单",
inputSchema: {
type: "object",
properties: {
orderId: { type: "string", description: "订单号" },
vinId: { type: "string", description: "车牌号" },
vin: { type: "string", description: "车辆识别码（可选）" },
},
required: ["orderId", "vinId"],
},
endpoint: { method: "GET", path: "/api/order/sdk/bindVehicle" },
},
// === 用户管理 ===
{
name: "get_user_roles",
description: "获取当前用户角色列表",
inputSchema: { type: "object", properties: {} },
endpoint: { method: "GET", path: "/api/user/roles" },
},
{
name: "get_user_by_openid",
description: "根据微信OpenID查询用户信息",
inputSchema: {
type: "object",
properties: {
wxOpenId: { type: "string", description: "微信OpenID" },
},
required: ["wxOpenId"],
},
endpoint: { method: "GET", path: "/api/user/openId/{wxOpenId}" },
},
{
name: "register_user",
description: "注册新用户（已存在则更新信息）",
inputSchema: {
type: "object",
properties: {
wxOpenId: { type: "string", description: "微信OpenID" },
wxUnionId: { type: "string", description: "微信UnionID" },
wxNickname: { type: "string", description: "微信昵称" },
phone: { type: "string", description: "手机号" },
},
required: ["wxOpenId", "wxUnionId"],
},
endpoint: { method: "POST", path: "/api/user/register" },
},
// === 微信登录 ===
{
name: "wx_login",
description: "微信小程序登录",
inputSchema: {
type: "object",
properties: {
appKey: { type: "string", description: "小程序标识（如：tlbc、tlbm）" },
code: { type: "string", description: "微信登录code" },
wxNickname: { type: "string", description: "微信昵称" },
phone: { type: "string", description: "手机号" },
phoneCode: { type: "string", description: "微信获取手机号的code" },
},
required: ["appKey", "code"],
},
endpoint: { method: "POST", path: "/api/wx/login" },
},
{
name: "wx_get_phone",
description: "通过微信code获取手机号",
inputSchema: {
type: "object",
properties: {
appKey: { type: "string", description: "小程序标识" },
phoneCode: { type: "string", description: "微信手机号code" },
},
required: ["appKey", "phoneCode"],
},
endpoint: { method: "POST", path: "/api/wx/phone" },
},
// === 内部管理（需要Admin Key）===
{
name: "admin_reaggregate_order_summary",
description: "重新聚合运单汇总（清空水位点和order_summary表，从头重新聚合），异步执行",
inputSchema: { type: "object", properties: {} },
endpoint: { method: "POST", path: "/api/admin/reaggregate-order-summary" },
requiresAdmin: true,
},
{
name: "admin_reconvert_order_status",
description: "重新推导订单状态（清空旧数据，从vehicle_status_duration重新推导），异步执行",
inputSchema: { type: "object", properties: {} },
endpoint: { method: "POST", path: "/api/admin/reconvert-order-status" },
requiresAdmin: true,
},
{
name: "admin_reconvert_stream_processor",
description: "重新推导订单状态（逐笔方式），清空上下文从头处理，异步执行",
inputSchema: { type: "object", properties: {} },
endpoint: { method: "POST", path: "/api/admin/reconvert-stream-processor" },
requiresAdmin: true,
},
{
name: "admin_reset_stream_processor",
description: "重置逐笔处理器上下文（清空水位点和所有上下文）",
inputSchema: { type: "object", properties: {} },
endpoint: { method: "POST", path: "/api/admin/reset-stream-processor" },
requiresAdmin: true,
},
];
// 创建 Server
const server = new Server(
{ name: "tlbm-mcp", version: "1.0.0" },
{ capabilities: { tools: {} } }
);
// 注册 list_tools handler
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: TOOLS.map((tool) => ({
name: tool.name,
description: tool.description,
inputSchema: tool.inputSchema,
})),
};
});
// 注册 call_tool handler
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
const tool = TOOLS.find((t) => t.name === name);
if (!tool) {
throw new Error(`Unknown tool: ${name}`);
}
// 检查 Admin Key
if (tool.requiresAdmin && !ADMIN_KEY) {
return {
content: [{ type: "text", text: "错误：需要设置 TLBM_ADMIN_KEY 环境变量才能调用内部管理接口" }],
};
}
try {
// 处理路径参数
let path = tool.endpoint.path;
const params = args ? { ...args } : {};
if (path.includes("{vinId}") && params.vinId) {
path = path.replace("{vinId}", String(params.vinId));
delete params.vinId;
}
if (path.includes("{outOrderNo}") && params.outOrderNo) {
path = path.replace("{outOrderNo}", String(params.outOrderNo));
delete params.outOrderNo;
}
if (path.includes("{orderId}") && params.orderId) {
path = path.replace("{orderId}", String(params.orderId));
delete params.orderId;
}
if (path.includes("{wxOpenId}") && params.wxOpenId) {
path = path.replace("{wxOpenId}", String(params.wxOpenId));
delete params.wxOpenId;
}
// 发送请求
const result = await httpRequest(
tool.endpoint.method,
path,
tool.endpoint.method === "GET" ? params : undefined,
tool.endpoint.method === "POST" ? params : undefined
);
return {
content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
};
} catch (error: any) {
return {
content: [{ type: "text", text: `错误: ${error.message}` }],
};
}
});
// 启动服务
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
}
main().catch(console.error);
tsconfig.json
+16
View File
@@ -0,0 +1,16 @@
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"lib": ["ES2020"],
"outDir": "dist",
"rootDir": "src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"declaration": true,
"resolveJsonModule": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}