hikvision-mcp

[!IMPORTANT] Software alfa para despliegues locales y de confianza. Pruebe con el modelo de cámara y el firmware exactos antes de habilitar escrituras.

Un servidor MCP local y consciente de capacidades para inspeccionar y configurar cámaras Hikvision de forma segura. La versión actual implementa el primer corte vertical de extremo a extremo del PRD:

• Configuración TOML y secretos mediante variables de entorno;

• aplicación de permisos por cámara y por herramienta;

• ISAPI asíncrono con autenticación digest, análisis XML seguro y transmisión de eventos acotada;

• sondeo de identidad y capacidades de la cámara;

• lectura de luz de advertencia y actualizaciones parciales de configuración mediante el esquema JSON de la cámara;

• regiones de intrusión, objetivos, horarios de activación y vinculación de eventos de solo lectura;

• reglas de solo lectura para movimiento, manipulación, cruce de línea, intrusión, entrada/salida de región y cambio de escena, con zonas, horarios, objetivos y vinculación;

• lecturas de estado de salud de la cámara, perfiles de flujo, configuración de imagen/día-noche, estado de almacenamiento, configuración de alarma audible y capacidades de audio bidireccional;

• monitoreo de alertas en vivo acotado con tipo de evento semántico y estado activo/inactivo;

• respaldo obligatorio de aprobación de propuesta/aplicación;

• detección de conflictos, lectura de verificación, historial de auditoría/cambios en SQLite y reversión;

• transportes MCP HTTP transmisible por stdio y localhost.

Los adaptadores de luz de advertencia, detección de campo y flujo de alertas tienen cobertura de fixtures sanitizados para el firmware DS-2CD2346G2-ISU/SL V5.7.14 y V5.7.19. La superficie de lectura ampliada tiene cobertura de fixtures sanitizados V5.7.19. Las escrituras de hardware aún requieren aprobación explícita y deben ser opcionales hasta que se valide un ciclo PUT/lectura en el objetivo. Las diferencias de firmware pertenecen a subclases de adaptadores, nunca a los manejadores MCP.

Compatibilidad

El hardware de referencia es un DS-2CD2346G2-ISU/SL. Otros dispositivos Hikvision se manejan mediante sondeo de capacidades, selección de canal automática o configurada, y registro de adaptadores de modelo/firmware; no se declaran como probados hasta que se agreguen fixtures sanitizados o evidencia de hardware.

Instalación

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

En Linux o macOS, use cp y export para la copia de archivos y los valores de entorno equivalentes.

Mantenga config.toml local y nunca confirme credenciales. Valide y ejecute:

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

El endpoint MCP HTTP es http://127.0.0.1:8000/mcp por defecto.

Flujo de mutación seguro

La configuración de ejemplo es de solo lectura. Eleve deliberadamente los techos de política del servidor y de la cámara al Nivel 3 antes de usar este flujo.

1. Llame a get_capabilities(camera="example_camera").

2. Llame a get_warning_light.

3. Llame a configure_warning_light; esto solo crea una propuesta.

4. Obtenga aprobación humana explícita.

5. Llame a apply_change(proposal_id=..., approved=true).

6. El servidor verifica conflictos, escribe una vez, lee de nuevo, verifica y audita.

7. Use rollback_change para crear una propuesta de reversión aprobada por separado.

Diagnósticos de solo lectura

• get_detection_rules(camera="example_camera") lee los tipos de detector anunciados por la cámara. Pase kinds para sondear tipos específicos. Cada resultado informa el soporte de forma independiente y conserva la configuración legible si los sub-recursos de horario o vinculación no están disponibles.

• get_camera_health, get_stream_profiles, get_image_settings y get_storage_status exponen el estado operativo sin permitir acciones de red, cuentas, firmware o reinicio.

• get_audio_alarm y get_two_way_audio describen la disuasión audible y la configuración del canal de voz. No reproducen audio, abren una sesión de voz ni cambian el estado de la cámara.

• get_intrusion_detection(camera="example_camera") devuelve la habilitación de detección de campo, regiones, polígonos, objetivos, sensibilidad, horario de activación y métodos de vinculación.

• monitor_events(camera="example_camera", duration_seconds=15) observa el flujo de alertas durante un período acotado. Use event_types=["fielddetection"] para filtrar nombres exactos de eventos de cámara.

• get_warning_light(camera="example_camera") devuelve duración, frecuencia y horario. El firmware de referencia V5.7.19 no anuncia brillo ni una bandera de habilitación independiente.

Controles de calidad

uv run ruff check .
uv run mypy
uv run pytest

Consulte CONFIGURATION.md, SECURITY.md y DEVELOPMENT.md.

Estado del proyecto y soporte

Este proyecto no está afiliado ni respaldado por Hikvision. Hikvision e ISAPI se utilizan solo para identificar productos y protocolos compatibles. El comportamiento del hardware y del firmware varía; las características no compatibles o desconocidas devuelven unsupported_capability en lugar de adivinarse.

Los informes de errores y las contribuciones son bienvenidos. Lea CONTRIBUTING.md antes de enviar cargas útiles de cámara o cambios, y use SECURITY.md para vulnerabilidades.

Licenciado bajo la Licencia MIT.