hikvision-mcp

[!WICHTIG] Alpha-Software für lokale, vertrauenswürdige Bereitstellungen. Testen Sie gegen Ihr genaues Kameramodell und die Firmware, bevor Sie Schreibvorgänge aktivieren.

Ein lokaler, fähigkeitsbewusster MCP-Server zur sicheren Inspektion und Konfiguration von Hikvision-Kameras. Die aktuelle Version implementiert den ersten durchgängigen vertikalen Schnitt des PRD:

• TOML-Konfiguration und Umgebungsvariablen-Geheimnisse;

• Durchsetzung von Berechtigungen pro Kamera und pro Werkzeug;

• asynchrones ISAPI mit Digest-Authentifizierung, sicherem XML-Parsing und begrenztem Ereignis-Streaming;

• Ermittlung von Kameraidentität und -fähigkeiten;

• Lesen der Warnleuchte und partielle Konfigurationsaktualisierungen mithilfe des JSON-Schemas der Kamera;

• schreibgeschützte Eindringregionen, Ziele, Scharfschaltpläne und Ereignisverknüpfung;

• schreibgeschützte Regeln für Bewegung, Manipulation, Linienkreuzung, Eindringen, Regionsein-/austritt und Szenenwechsel mit Zonen, Zeitplänen, Zielen und Verknüpfung;

• Kamera-Gesundheit, Stream-Profile, Bild-/Tag-Nacht-Einstellungen, Speicherstatus, Konfiguration des akustischen Alarms und Lesen der Zwei-Wege-Audio-Fähigkeiten;

• begrenzte Live-Alarmüberwachung mit semantischem Ereignistyp und aktivem/inaktivem Zustand;

• obligatorischer Vorschlags-/Anwendungs-Genehmigungs-Fallback;

• Konflikterkennung, verifiziertes Rücklesen, SQLite-Audit-/Änderungsverlauf und Rollback;

• stdio- und localhost-Streamable-HTTP-MCP-Transports.

Die Adapter für Warnleuchte, Felderkennung und Alarmstrom haben bereinigte Fixture-Abdeckung für DS-2CD2346G2-ISU/SL-Firmware V5.7.14 und V5.7.19. Die erweiterte Leseoberfläche hat bereinigte V5.7.19-Fixture-Abdeckung. Hardware-Schreibvorgänge erfordern weiterhin ausdrückliche Genehmigung und sollten bis zur Validierung eines PUT-/Rücklese-Zyklus auf dem Zielgerät nur optional sein. Firmware-Unterschiede gehören in Adapter-Unterklassen, niemals in MCP-Handler.

Kompatibilität

Die Referenzhardware ist eine DS-2CD2346G2-ISU/SL. Andere Hikvision-Geräte werden über Fähigkeitsabfrage, automatische oder konfigurierte Kanalauswahl und Modell-/Firmware-Adapterregistrierung behandelt; sie gelten nicht als getestet, bis bereinigte Fixtures oder Hardware-Nachweise hinzugefügt werden.

Installation

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

Verwenden Sie unter Linux oder macOS cp und export für das entsprechende Dateikopieren und die Umgebungsvariablen.

Halten Sie config.toml lokal und übergeben Sie niemals Anmeldedaten. Validieren und ausführen:

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

Der HTTP-MCP-Endpunkt ist standardmäßig http://127.0.0.1:8000/mcp.

Sicherer Mutationsablauf

Die Beispielkonfiguration ist schreibgeschützt. Erhöhen Sie bewusst sowohl die Server- als auch die Kamera-Richtlinienobergrenzen auf Stufe 3, bevor Sie diesen Ablauf verwenden.

1. Rufen Sie get_capabilities(camera="example_camera") auf.

2. Rufen Sie get_warning_light auf.

3. Rufen Sie configure_warning_light auf; dies erstellt nur einen Vorschlag.

4. Holen Sie ausdrückliche menschliche Genehmigung ein.

5. Rufen Sie apply_change(proposal_id=..., approved=true) auf.

6. Der Server prüft auf Konflikte, schreibt einmal, liest zurück, verifiziert und protokolliert.

7. Verwenden Sie rollback_change, um einen separat genehmigten Rollback-Vorschlag zu erstellen.

Schreibgeschützte Diagnose

• get_detection_rules(camera="example_camera") liest die von der Kamera beworbenen Detektortypen. Übergeben Sie kinds, um bestimmte Typen zu prüfen. Jedes Ergebnis meldet die Unterstützung unabhängig und bewahrt lesbare Konfiguration, wenn Zeitplan- oder Verknüpfungs-Unterressourcen nicht verfügbar sind.

• get_camera_health, get_stream_profiles, get_image_settings und get_storage_status legen Betriebszustand offen, ohne Netzwerk, Konten, Firmware oder Reset-Aktionen zu erlauben.

• get_audio_alarm und get_two_way_audio beschreiben akustische Abschreckung und Sprechkanal-Konfiguration. Sie spielen kein Audio ab, öffnen keine Sprechsitzung und ändern keinen Kamerazustand.

• get_intrusion_detection(camera="example_camera") gibt Aktivierung der Felderkennung, Regionen, Polygone, Ziele, Empfindlichkeit, Scharfschaltplan und Verknüpfungsmethoden zurück.

• monitor_events(camera="example_camera", duration_seconds=15) überwacht den Alarmstrom für einen begrenzten Zeitraum. Verwenden Sie event_types=["fielddetection"], um nach genauen Kamera-Ereignisnamen zu filtern.

• get_warning_light(camera="example_camera") gibt Dauer, Frequenz und Zeitplan zurück. Die Referenz-Firmware V5.7.19 bewirbt keine Helligkeit oder ein eigenständiges Aktivierungsflag.

Qualitätsprüfungen

uv run ruff check .
uv run mypy
uv run pytest

Siehe CONFIGURATION.md, SECURITY.md und DEVELOPMENT.md.

Projektstatus und Support

Dieses Projekt ist nicht mit Hikvision verbunden oder von Hikvision unterstützt. Hikvision und ISAPI werden nur zur Identifizierung kompatibler Produkte und Protokolle verwendet. Hardware- und Firmware-Verhalten variiert; nicht unterstützte oder unbekannte Funktionen geben unsupported_capability zurück, anstatt geraten zu werden.

Fehlerberichte und Beiträge sind willkommen. Lesen Sie CONTRIBUTING.md, bevor Sie Kamera-Payloads oder Änderungen einreichen, und verwenden Sie SECURITY.md für Sicherheitslücken.

Lizenziert unter der MIT-Lizenz.