臻识停车 MCP

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

安装与启动

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

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

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

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

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

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

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

环境变量示例见 .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 客户端配置示例（路径和凭据按实际环境替换）：

[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个工具。操作开关在进程启动时读取，修改后重启服务。

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

分页查询均提供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解析失败。详见查询验证记录。

结构化结果与错误

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

{
  "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文档。

验证与开发

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

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