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,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);