cams_charge_get_user_stub_groups 0.1.0__tar.gz

cams_charge_get_user_stub_groups-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+build/
+dist/

cams_charge_get_user_stub_groups-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: cams_charge_get_user_stub_groups
+Version: 0.1.0
+Summary: Charging assistant MCP: get_user_stub_groups
+Requires-Python: >=3.10
+Requires-Dist: fastmcp<4,>=3.4
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'

cams_charge_get_user_stub_groups-0.1.0/curl.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# 测试 get_user_stub_groups: GET <BASE>/mts/ai/getUserStubGroups?userId=${USER_ID}&lng=${LNG}&lat=${LAT}
+# 用法: CHARGE_BACKEND_BASE_URL=http://<后端host> bash curl.sh
+set -euo pipefail
+BASE="${CHARGE_BACKEND_BASE_URL:-http://localhost:8080}"
+USER_ID="${USER_ID:-77d12b73-7f5a-4abb-97e2-63a13d3d2732}"
+STUB_ID="${STUB_ID:-2023100909}"
+LAT="${LAT:-31.641665}"
+LNG="${LNG:-119.889879}"
+CHARGE_ID="${CHARGE_ID:-<从 exec_start_charging 返回取>}"
+STATION_ID="${STATION_ID:-<从 get_nearby_station 返回取>}"
+echo "-> GET ${BASE}/mts/ai/getUserStubGroups?userId=${USER_ID}&lng=${LNG}&lat=${LAT}"
+curl -sS "${BASE}/mts/ai/getUserStubGroups?userId=${USER_ID}&lng=${LNG}&lat=${LAT}" | python3 -m json.tool

cams_charge_get_user_stub_groups-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "cams_charge_get_user_stub_groups"
+version = "0.1.0"
+description = "Charging assistant MCP: get_user_stub_groups"
+requires-python = ">=3.10"
+dependencies = ["fastmcp>=3.4,<4", "requests>=2.31"]
+
+[project.scripts]
+cams-charge-get-user-stub-groups = "cams_charge_get_user_stub_groups.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cams_charge_get_user_stub_groups"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "responses>=0.25"]

cams_charge_get_user_stub_groups-0.1.0/src/cams_charge_get_user_stub_groups/__init__.py

@@ -0,0 +1 @@
+"""cams_charge_get_user_stub_groups MCP server."""

cams_charge_get_user_stub_groups-0.1.0/src/cams_charge_get_user_stub_groups/client.py

@@ -0,0 +1,304 @@
+"""Vendored charging-backend HTTP client + response normalizer.
+
+CANONICAL COPY: mcps/common/client.py
+Copied verbatim into every cams_charge_* package at src/<pkg>/client.py.
+Edit here, then re-copy into each package (keep them byte-identical).
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping
+
+import requests
+
+
+# 桩状态码 → 中文标签（对齐后端 StubStatusMenu.java）。00=空闲是唯一可启动状态。
+STATUS_LABELS: dict[str, str] = {
+    "00": "空闲", "01": "充电中", "02": "故障", "03": "车位占用",
+    "04": "维护中", "10": "维修中", "05": "离线", "06": "在建中",
+    "07": "桩程序升级", "08": "预约等待充电中", "09": "储能中",
+    "99": "删除", "ff": "锁定不允许充电", "0A": "离线启动",
+    "0B": "已插枪", "0D": "已插枪", "0C": "在线预约中",
+}
+
+# 后端成功 code（字符串 "200"，非 0）
+_OK_CODES = {"200", "0"}
+
+# 预约订单状态（UserStubReservationStatus.java）：0 已取消 / 1 预约中 / 2 预约保留中 / 3 预约中超时 / 9 已充电
+RESERVATION_STATUS = {"0": "已取消", "1": "预约中", "2": "预约保留中", "3": "预约中超时", "9": "已充电"}
+_RESERVING = {"1", "2"}  # judgeIsReserving：进行中
+
+# 地锁物理状态（ParkinglockStatusEnum.java，stubInfo.lockStatus）
+LOCK_STATUS = {"0": "已降下", "1": "已升起", "2": "故障", "3": "已锁车", "4": "已休眠", "5": "未知", "6": "离网", "9": "占用中"}
+_LOCK_FREE = {"1", "4"}  # checkIsFree：地锁空闲(不挡车)
+
+
+def _base_url() -> str:
+    val = os.environ.get("CHARGE_BACKEND_BASE_URL", "").strip().rstrip("/")
+    if not val:
+        raise RuntimeError("CHARGE_BACKEND_BASE_URL 未设置")
+    return val
+
+
+def _servlet() -> str:
+    return os.environ.get("CHARGE_BACKEND_SERVLET", "mts").strip().strip("/")
+
+
+def _timeout() -> float:
+    try:
+        return float(os.environ.get("CHARGE_BACKEND_TIMEOUT", "10"))
+    except ValueError:
+        return 10.0
+
+
+def _token() -> str | None:
+    return os.environ.get("CHARGE_BACKEND_TOKEN") or None
+
+
+def _resolved_method(default: str) -> str:
+    return os.environ.get("CHARGE_METHOD_NAME") or default
+
+
+def _coerce_form(form: Mapping[str, Any] | None) -> dict[str, str]:
+    out: dict[str, str] = {}
+    if not form:
+        return out
+    for k, v in form.items():
+        if v is None:
+            continue
+        out[k] = v if isinstance(v, str) else str(v)
+    return out
+
+
+def request_platform_api(
+    default_method_name: str,
+    form: Mapping[str, Any] | None = None,
+    *,
+    method_name_override: str | None = None,
+) -> dict[str, Any]:
+    """调用一个充电后台 methodName。绝不向调用方抛异常；始终返回结果 dict。
+
+    返回:
+      {"ok": True, "data": <data>}                              成功(code=="200")
+      {"ok": False, "code": str, "msg": str, "suggestion": str} 业务失败(code!=200)
+      {"ok": False, "error": str, "suggestion": str}           网络/解析错误
+
+    请求方式: GET, 参数以 query 串传递 (application/x-www-form-urlencoded)。
+    后端信封: {"code":"200","text":...,"data":...,"pageLimit":null}，成功 code="200"。
+    """
+    method_name = method_name_override or _resolved_method(default_method_name)
+    url = f"{_base_url()}/{_servlet()}/{method_name.lstrip('/')}"
+    payload = _coerce_form(form)
+    headers = {}
+    token = _token()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    try:
+        resp = requests.get(url, params=payload, headers=headers, timeout=_timeout())
+    except requests.RequestException as exc:
+        return {"ok": False, "error": f"网络请求失败: {exc}",
+                "suggestion": "请稍后重试；持续失败请联系平台排查后端连通性。"}
+
+    try:
+        body = resp.json()
+    except ValueError:
+        return {"ok": False, "error": f"后端返回非JSON (HTTP {resp.status_code})",
+                "suggestion": "后端可能返回HTML错误页；请检查 methodName 与 servlet 配置。"}
+
+    if isinstance(body, dict) and "code" in body:
+        code = body.get("code")
+        msg = body.get("text") or body.get("msg", "")
+        if str(code) in _OK_CODES:
+            return {"ok": True, "data": body.get("data")}
+        return {"ok": False, "code": code, "msg": msg,
+                "suggestion": _biz_suggestion(code, msg)}
+    return {"ok": True, "data": body}
+
+
+def _biz_suggestion(code: Any, msg: str) -> str:
+    return f"业务失败 code={code}: {msg}。可引导用户重试或更换目标桩/场站。"
+
+
+# ───────────────────────── 归一化（精简字段，去噪） ─────────────────────────
+
+def status_label(code: Any) -> str:
+    if code is None:
+        return "未知"
+    return STATUS_LABELS.get(str(code), str(code))
+
+
+def is_idle(code: Any) -> bool:
+    return str(code) == "00"
+
+
+def _norm_stub(s: Any) -> Any:
+    if not isinstance(s, dict):
+        return s
+    status = s.get("status")
+    pl = s.get("parkingLockId")
+    si = s.get("stubInfo") if isinstance(s.get("stubInfo"), dict) else {}
+    lock_status = si.get("lockStatus")
+    lock_s = str(lock_status) if lock_status not in (None, "") else None
+    return {
+        "stubId": s.get("id"),
+        "name": s.get("name"),
+        "kw": s.get("kw"),
+        "chargingMode": s.get("chargingMode"),
+        "status": status,
+        "statusLabel": status_label(status),
+        "idle": is_idle(status),
+        "reservable": str(s.get("reservable")) in ("1", "true", "True"),
+        "hasLock": bool(pl),
+        "parkingLockId": pl,
+        "lockStatus": lock_status,
+        "lockStatusLabel": LOCK_STATUS.get(lock_s, lock_s) if lock_s else None,
+        "lockFree": lock_s in _LOCK_FREE,
+        "isVinPlugAndCharge": bool(s.get("isVinPlugAndCharge")),
+        "totalFee": s.get("totalFee"),
+    }
+
+
+def _norm_stub_detail(s: Any) -> Any:
+    """桩详情（get_stub_info，单桩）：在 _norm_stub 基础上补场站上下文 + 充电订单号/开始时间。"""
+    base = _norm_stub(s)
+    if not isinstance(base, dict):
+        return base
+    si = s.get("stubInfo") if isinstance(s.get("stubInfo"), dict) else {}
+    base["stubGroupId"] = s.get("stubGroupId")
+    base["stubGroupName"] = s.get("stubGroupName")
+    base["stubGroupAddress"] = s.get("stubGroupAddress")
+    base["chargeOrderId"] = si.get("orderId")  # 充电中(status=01)时的充电订单号，可作 exec_stop 的 chargeId 兜底
+    base["chargeStartTime"] = si.get("chargeStartTime")
+    return base
+
+
+def _norm_station(s: Any) -> Any:
+    if not isinstance(s, dict):
+        return s
+    stubs = s.get("stubList") or []
+    reservable_raw = s.get("reservable")
+    if reservable_raw is None:
+        reservable_raw = s.get("isReservable")  # nearby/user_stub_groups 用 isReservable
+    price = s.get("currentPrice")
+    return {
+        "stationId": s.get("id"),
+        "name": s.get("name"),
+        "address": s.get("address"),
+        "lat": s.get("gisGcj02Lat"),
+        "lng": s.get("gisGcj02Lng"),
+        "distance": s.get("distance"),
+        "serviceTime": s.get("serviceTime"),
+        "parkingFree": s.get("parkingFree"),
+        "parkingFeeInfo": s.get("parkingFeeInfo"),
+        "reservable": reservable_raw in (True, "true", "1", 1),
+        "isFavorite": bool(s.get("isFavorite")),
+        "notice": s.get("stubGroupInfo") or s.get("noticInfo"),
+        "currentPrice": price.get("value") if isinstance(price, dict) else None,
+        "totalFee": s.get("totalFee"),
+        "placeholderInfo": s.get("placeholderInfo"),
+        "stubCount": len(stubs),
+        "stubs": [_norm_stub(x) for x in stubs],
+    }
+
+
+def _norm_station_list(data: Any) -> Any:
+    """场站列表归一；null/非列表 → []（getUserStubGroups 的 userPreferStubGroupList 可为 null）。"""
+    if isinstance(data, list):
+        return [_norm_station(s) for s in data]
+    return []
+
+
+def _norm_user_stub_groups(data: Any) -> Any:
+    if not isinstance(data, dict):
+        return data
+    return {
+        "near": _norm_station_list(data.get("nearStubGroupList")),
+        "favorite": _norm_station_list(data.get("favoriteStubGroupList")),
+        "prefer": _norm_station_list(data.get("userPreferStubGroupList")),
+    }
+
+
+def _norm_exec(data: Any) -> Any:
+    """exec_* 成功返回的订单对象：best-effort 提取 charge/order id（字段名待成功样本确认）。"""
+    if isinstance(data, dict):
+        for k in ("chargeId", "chargeNo", "orderId", "orderNo", "chargeOrderId", "id"):
+            if data.get(k):
+                return {"id": data.get(k), "raw": data}
+    return data
+
+
+def _norm_reservation(data: Any) -> Any:
+    """预约订单（get_reserve_order，单个对象或 null）：提取关键字段 + 状态映射。"""
+    if not isinstance(data, dict):
+        return data
+    status = data.get("status")
+    status_s = str(status) if status is not None else None
+    return {
+        "reservationId": data.get("id"),
+        "userId": data.get("accountId"),
+        "stubId": data.get("stubId"),
+        "stubName": data.get("stubName"),
+        "stubGroupId": data.get("stubGroupId"),
+        "stubGroupName": data.get("stubGroupName"),
+        "address": data.get("address"),
+        "carId": data.get("carId"),
+        "licencePlate": data.get("licencePlate"),
+        "brandName": data.get("brandName"),
+        "status": status,
+        "statusLabel": RESERVATION_STATUS.get(status_s, status_s) if status_s else "未知",
+        "active": status_s in _RESERVING,
+        "reservateTime": data.get("reservateTime"),
+        "reserveEndTime": data.get("reserveEndTime"),
+        "reserveMinutes": data.get("reserveMinutes"),
+        "unlockTime": data.get("unlockTime"),
+        "cancelTime": data.get("cancelTime"),
+        "lat": data.get("gisGcj02Lat"),
+        "lng": data.get("gisGcj02Lng"),
+    }
+
+
+def _norm_parking_order(data: Any) -> Any:
+    """地锁订单（ParkingOrder）：提取关键字段。"""
+    if not isinstance(data, dict):
+        return data
+    return {
+        "parkingOrderId": data.get("parkingOrderId"),
+        "id": data.get("id"),
+        "chargeOrderId": data.get("chargeOrderId"),
+        "stubId": data.get("stubId"),
+        "userId": data.get("userId"),
+        "startTime": data.get("startTime"),
+        "endTime": data.get("endTime"),
+        "status": data.get("status"),
+        "createTime": data.get("createTime"),
+    }
+
+
+def _norm_lock_orders(data: Any) -> Any:
+    """get_lock_order：ParkingOrder 列表归一；空列表([])表示无进行中地锁订单。"""
+    if isinstance(data, list):
+        return [_norm_parking_order(x) for x in data]
+    return data
+
+
+def normalize(tool: str, data: Any) -> Any:
+    """按工具名把后端原始 data 归一为精简结构。未知/空样本透传。"""
+    if data is None:
+        return None
+    if tool == "get_nearby_station":
+        return _norm_station_list(data)
+    if tool == "get_user_stub_groups":
+        return _norm_user_stub_groups(data)
+    if tool == "get_station_detail":
+        return _norm_station(data)
+    if tool == "get_stub_info":
+        return _norm_stub_detail(data)
+    if tool in ("exec_reserve_stub", "exec_unlock_ground",
+                "exec_start_charging", "exec_stop_charging"):
+        return _norm_exec(data)
+    if tool == "get_reserve_order":
+        return _norm_reservation(data)
+    if tool == "get_lock_order":
+        return _norm_lock_orders(data)
+    return data

cams_charge_get_user_stub_groups-0.1.0/src/cams_charge_get_user_stub_groups/server.py

@@ -0,0 +1,29 @@
+from fastmcp import FastMCP
+
+from .client import request_platform_api, normalize
+
+mcp = FastMCP("get-user-stub-groups")
+
+
+def get_user_stub_groups(user_id: str, user_lat: float, user_lng: float) -> dict:
+    """工具名称: get_user_stub_groups
+核心功能: 查询用户电站：一次返回附近/收藏/常用三个列表(每个场站含桩列表 stubs[])。用户说「我收藏的」「常去」「我的电站」时调用。
+后端接口: GET {BASE}/{servlet}/ai/getUserStubGroups  query: userId, lng, lat
+入参: user_id: str, user_lat: float, user_lng: float
+返回: {"ok":True,"data":<归一化结果>} 或 {"ok":False,"code":..,"msg":..,"suggestion":..} / {"ok":False,"error":..,"suggestion":..}
+"""
+    r = request_platform_api("ai/getUserStubGroups", form={"userId": user_id, "lng": user_lng, "lat": user_lat})
+    if r.get("ok"):
+        r["data"] = normalize("get_user_stub_groups", r.get("data"))
+    return r
+
+
+mcp.tool(name="get_user_stub_groups", description=get_user_stub_groups.__doc__)(get_user_stub_groups)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

cams_charge_get_user_stub_groups-0.1.0/tests/test_tool.py

@@ -0,0 +1,32 @@
+import responses
+
+from cams_charge_get_user_stub_groups.server import get_user_stub_groups
+
+BASE = "https://charge.test"
+
+
+def _query(call) -> str:
+    return call.request.url
+
+
+@responses.activate
+def test_ok(monkeypatch):
+    monkeypatch.setenv("CHARGE_BACKEND_BASE_URL", BASE)
+    monkeypatch.setenv("CHARGE_BACKEND_SERVLET", "mts")
+    responses.add(
+        responses.GET, f"{BASE}/mts/ai/getUserStubGroups",
+        json={"code": "200", "text": None, "data": {"ok": True}}, status=200)
+    r = get_user_stub_groups(user_id="77d12b73-7f5a-4abb-97e2-63a13d3d2732", user_lat=31.641665, user_lng=119.889879)
+    assert r["ok"] is True
+    q = _query(responses.calls[0])
+    for f in ['userId=77d12b73-7f5a-4abb-97e2-63a13d3d2732', 'lng=119.889879', 'lat=31.641665']:
+        assert f in q, f"missing query param {f} in {q!r}"
+
+
+@responses.activate
+def test_biz_error(monkeypatch):
+    monkeypatch.setenv("CHARGE_BACKEND_BASE_URL", BASE)
+    responses.add(responses.GET, f"{BASE}/mts/ai/getUserStubGroups",
+                  json={"code": "010212", "text": "该终端暂不可用"}, status=200)
+    r = get_user_stub_groups(user_id="77d12b73-7f5a-4abb-97e2-63a13d3d2732", user_lat=31.641665, user_lng=119.889879)
+    assert r["ok"] is False and r["code"] == "010212"