hikvision-mcp

[!IMPORTANT] 面向本地受信任部署环境的 Alpha 软件。在启用写入之前，请针对你的确切摄像机型号和固件进行测试。

一个本地、具备能力感知功能的 MCP 服务器，用于安全地检查和配置 Hikvision 摄像机。当前版本实现了 PRD 的第一个端到端纵向切片：

• TOML 配置与环境变量机密；

• 逐摄像机、逐工具权限强制；

• 支持摘要认证的异步 ISAPI、安全 XML 解析和有界事件流；

• 摄像机身份与能力探测；

• 报警灯读取，以及使用摄像机 JSON schema 进行部分配置更新；

• 只读的入侵区域、目标、布防计划和事件联动；

• 只读的移动侦测、镜头遮挡、越界侦测、入侵侦测、区域进入/离开和场景变更规则，包含区域、布防计划、目标和联动；

• 摄像机健康状态、码流配置、图像/日夜设置、存储状态、音频报警配置和双向语音能力读取；

• 有界的实时报警监控，带语义事件类型和活动/非活动状态；

• 强制的提案/应用审批回退；

• 冲突检测、经核验的回读、SQLite 审计/变更历史和回滚；

• stdio 和 localhost 上的 Streamable HTTP MCP 传输方式。

报警灯、区域侦测和报警流适配器已针对 DS-2CD2346G2-ISU/SL 固件 V5.7.14 和 V5.7.19 提供脱敏测试夹具覆盖。扩展的只读功能面已具备脱敏的 V5.7.19 测试夹具覆盖。硬件写入仍需要明确审批，并且在目标设备上完成 PUT/回读验证之前，应默认不启用。固件差异应放在适配器子类中，绝不应放在 MCP 处理器中。

兼容性

参考硬件为 DS-2CD2346G2-ISU/SL。其他 Hikvision 设备通过能力探测、自动或配置的通道选择以及型号/固件适配器注册来处理；在添加脱敏测试夹具或硬件证据之前，不宣称其已经过测试。

安装

uv sync --extra dev
Copy-Item config.example.toml config.toml
$env:HIKVISION_CAMERA_USERNAME = "service-account"
$env:HIKVISION_CAMERA_PASSWORD = "..."

在 Linux 或 macOS 上，使用 cp 和 export 进行等效的文件复制与设置环境变量。

将 config.toml 保留在本地，切勿提交凭证。验证并运行：

uv run hikvision-mcp config validate --config config.toml
uv run hikvision-mcp serve --transport stdio --config config.toml
uv run hikvision-mcp serve --transport streamable-http --config config.toml

HTTP MCP 端点默认为 http://127.0.0.1:8000/mcp。

安全变更流程

示例配置为只读。在使用此流程之前，请刻意将服务器和摄像机策略上限均提升到 Level 3。

1. 调用 get_capabilities(camera="example_camera")。

2. 调用 get_warning_light。

3. 调用 configure_warning_light；这只会创建一个提案。

4. 获得明确的人工审批。

5. 调用 apply_change(proposal_id=..., approved=true)。

6. 服务器检查冲突、写入一次、回读并验证和审计。

7. 使用 rollback_change 创建一个需单独审批的回滚提案。

只读诊断

• get_detection_rules(camera="example_camera") 读取摄像机通告的侦测器类型。传入 kinds 可探测特定类型。每个结果独立报告支持情况，并在布防计划或联动子资源不可用时保留可读配置。

• get_camera_health、get_stream_profiles、get_image_settings 和 get_storage_status 暴露运行状态，但不允许网络、账户、固件或重置操作。

• get_audio_alarm 和 get_two_way_audio 描述声音威慑和语音通道配置。它们不会播放音频、打开语音会话或改变摄像机状态。

• get_intrusion_detection(camera="example_camera") 返回区域侦测的启用状态、区域、多边形、目标、灵敏度、布防计划和联动方式。

• monitor_events(camera="example_camera", duration_seconds=15) 在有界时间段内监视报警流。使用 event_types=["fielddetection"] 可精确筛选摄像机事件名称。

• get_warning_light(camera="example_camera") 返回持续时间、频率和布防计划。参考 V5.7.19 固件不通告亮度或独立的启用标志。

质量检查

uv run ruff check .
uv run mypy
uv run pytest

请参阅 CONFIGURATION.md、SECURITY.md 和 DEVELOPMENT.md。

项目状态与支持

本项目与 Hikvision 无关联，也未获得其认可。Hikvision 和 ISAPI 仅用于标识兼容的产品和协议。硬件和固件行为存在差异；不受支持或未知的功能会返回 unsupported_capability，而不是被猜测。

欢迎提交问题报告和贡献。在提交摄像机数据负载或更改之前，请阅读 CONTRIBUTING.md；如需报告漏洞，请使用 SECURITY.md。

本项目依据 MIT License 授权。