Metadata-Version: 2.4
Name: vzenith-parking-mcp
Version: 0.1.0
Summary: MCP stdio server for the Vzenith parking platform
Project-URL: Repository, https://cnb.cool/leliven/leliven-mcp-skill
Keywords: mcp,vzenith,parking,fastmcp
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp<2.0,>=1.30
Requires-Dist: pydantic<3,>=2
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: python-dotenv<2,>=1

# 臻识停车 MCP

Python 3.11 + 官方 MCP Python SDK FastMCP + Pydantic 2 + httpx，stdio 单用户进程，uv 管理依赖，setuptools 打包。技术结构与同仓库 dahua-device-mcp 一致；认证使用臻识平台协议。

## 安装与启动

使用 Python 3.11 或以上版本，可通过 PyPI 安装：

```powershell
pip install vzenith-parking-mcp==0.1.0
vzenith-parking-mcp
```

也可通过 uv 临时运行，无需预先安装：

```powershell
uvx --from vzenith-parking-mcp==0.1.0 vzenith-parking-mcp
```

从本仓库源码运行（先进入 vzenith-parking-mcp 目录）：

```powershell
uv sync --locked
uv run --locked vzenith-parking-mcp
```

也支持 `uv run --locked python -m vzenith_parking_mcp`。stdout 只输出 MCP 协议，日志写 stderr。列出工具不需要联网；首次业务请求才建立登录会话。

环境变量示例见 [.env.example](.env.example)。配置完整 `VZENITH_AUTHORIZATION` 原值，或 `VZENITH_USERNAME` 与原始 `VZENITH_PASSWORD`。不自动添加 Bearer。原始密码按 UTF-8 计算 MD5 小写32位摘要后用于 POST /login；Token仅在内存缓存。401不重放当前请求，后续调用可重新登录；固定Token失效且未配置账号时需更新Token。403不无限登录。HTTPS证书验证开启，不跟随重定向。

默认不读取当前目录 .env；需要时显式使用 `--env-file E:/secure/vzenith.env`，已设置的环境变量优先。不要将真实凭据提交到仓库或配置示例中。

Codex 客户端配置示例（路径和凭据按实际环境替换）：

```toml
[mcp_servers.vzenith_parking]
command = "uv"
args = ["--directory", "E:/leliven-mcp-skill/vzenith-parking-mcp", "run", "--locked", "vzenith-parking-mcp"]

[mcp_servers.vzenith_parking.env]
VZENITH_AUTHORIZATION = "<完整Token原值>"
ENABLE_EXPERIMENTAL = "false"
ENABLE_WRITES = "false"
```

## 工具范围

完整目录29个业务工具，对应30个HTTP操作；原27号小程序视频接口不实现、不注册。默认11个查询；ENABLE_EXPERIMENTAL=true追加6个实验工具，并启用parking_list的options分支；ENABLE_WRITES=true追加12个写工具。全部开关开启时共29个工具。操作开关在进程启动时读取，修改后重启服务。

| 分组 | 工具 |
| --- | --- |
| 统计报表 | stat_berths_list、stat_parking_list、stat_devices_list |
| 车场管理 | parking_list、parking_update、parking_delete_batch、parking_create_batch |
| 车场分组管理 | parking_groups_list、parking_group_create、parking_group_update、parking_group_delete |
| 泊位管理 | berth_list |
| 设备管理 | device_list、device_count、device_bind_batch、device_update_batch、device_unbind_batch |
| 远程访问与视频（实验） | device_video_url_get、device_frontend_access_get |
| 配置与升级 | firmware_list、device_upgrade_batch、device_config_upload_token_get（实验）、device_latest_config_get（实验）、device_configs_apply、device_abnormal_config_enable |
| 运行诊断与识别 | device_latest_record_get（实验）、device_battery_history、device_traffic_history（实验）、device_logs_list |

车场查询合并为 parking_list：默认 view=detail，page=1、size=12，按create_time排序；view=options使用/parking/all，精简全量、分组ID归一为group_id，不能传page/size/order。不再注册parking_options_list。上游路径和原返回字段仍分别记在[API文档](vzenith-parking-api.md)。

分页查询均提供page/size，返回has_more/next_page；末页或空页停止，不把当前页长度当作total。统计查询不传时间时使用上海最近七个自然日；上游未筛选时的默认统计范围仍未确认。时间使用Unix秒，GET缓存参数t由服务以毫秒生成。

firmware_list接受page/size/version/remark，关键词会生成标准Base64 wheres，支持组合筛选；不上传或下载固件。关键词限单行128字符；大小上限、批量数量等属于工具本地约束，不代表已验证上游限制。

2026-10-27全量查询实测：17个查询工具、27个场景，25个HTTP200且通过返回schema校验；basic_config及特定固件关键词组合仍返回上游400。日志查询的start_time/end_time必须为整数秒，不能传小数，避免上游JSON int64解析失败。详见[查询验证记录](docs/query-verification.md)。

## 结构化结果与错误

成功和失败均返回相同的JSON文本content与structuredContent，成功isError=false，失败isError=true。工具包含outputSchema和四类行为注解。

```json
{
  "result": null,
  "meta": {"tool": "parking_list", "http_status": 401, "upstream_path": null, "view": null, "total_source": null},
  "error": {"code": "upstream_unauthorized", "message": "请检查会话与权限；本次请求不重放，后续调用可重新登录"}
}
```

主要错误类别：invalid_arguments、configuration_error、feature_disabled、authentication_failed、upstream_unauthorized、upstream_timeout、upstream_transport_error、upstream_error、upstream_response_invalid、partial_failure。未知参数、错误枚举、空ID数组和不成对时间会在请求前拒绝。错误不回显原输入、密码或上游原始错误正文。

设备列表及固件列表默认投影业务字段，凭据递归脱敏；自由日志原文与设备状态JSON原文保守省略，防止其中嵌入密码。媒体/设备访问URL的查询授权值被脱敏，结果不应视作可直接播放的完整地址；本服务不播放视频或上传文件。其他型号扩展字段仅在文档未确认部分保持通用结构，不编造字段语义。

写操作只在显式配置开关后注册，不自动重试。网络超时、取消、连接异常和部分失败不得自动重放；需使用相应列表核对实际状态。批量failures非空时返回partial_failure并保留脱敏逐项结果。空2xx写响应保留result=null，不宣称已读回验证。成功不等于配置已应用、固件已升级或设备在线。未执行生产写入联调，参数及返回契约的已知限制见API文档。

## 验证与开发

```powershell
uv run --locked python -m unittest discover -s tests -v
```

测试使用httpx.MockTransport，不访问生产写接口。协议烟测会通过真实stdio进程完成initialize、tools/list与无凭据查询错误验证。固定样本的多工具评估见tests/evaluation.xml，不以实时在线数或最新日志作为稳定答案。实现覆盖与验证结果见[实施记录](docs/implementation.md)。
