hikvision-mcp

[!IMPORTANT] ローカルでの信頼できるデプロイ向けのアルファソフトウェアです。書き込みを有効にする前に、お使いのカメラモデルと ファームウェアでテストしてください。

Hikvisionカメラを安全に検査・設定するための、ローカルで機能認識型のMCPサーバーです。現在のリリースは、PRDの最初のエンドツーエンドの垂直スライスを実装しています：

• TOML設定と環境変数によるシークレット管理；

• カメラ単位・ツール単位の権限強制；

• ダイジェスト認証、安全なXML解析、および時間制限付きイベントストリーミングを備えた非同期ISAPI；

• カメラの識別情報と機能のプロービング；

• カメラのJSONスキーマを使用した警告灯の読み取りと部分的な設定更新；

• 読み取り専用の侵入検知エリア、ターゲット、スケジュール、イベント連動；

• ゾーン、スケジュール、ターゲット、連動を含む、読み取り専用の動体検知、タンパー、ライン交差、侵入、領域出入り、シーン変化ルール；

• カメラのヘルス、ストリームプロファイル、画像/昼夜設定、ストレージステータス、可聴アラーム設定、双方向オーディオ機能の読み取り；

• 意味的なイベントタイプとアクティブ/非アクティブ状態を備えた、時間制限付きライブアラート監視；

• 必須の提案/適用承認フォールバック；

• 競合検出、検証済み読み戻し、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. サーバーは競合をチェックし、1回書き込み、読み戻し、検証、監査を行います。

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による承認も受けていません。HikvisionおよびISAPIは、互換性のある製品とプロトコルを識別するためにのみ使用されています。ハードウェアとファームウェアの動作は異なります。サポートされていない機能や不明な機能は推測されず、unsupported_capabilityを返します。

バグ報告とコントリビューションを歓迎します。カメラのペイロードや変更を送信する前にCONTRIBUTING.mdをお読みください。脆弱性についてはSECURITY.mdを使用してください。

MIT Licenseの下でライセンスされています。