hikvision-mcp

[!IMPORTANT] 로컬 및 신뢰할 수 있는 배포 환경을 위한 알파 단계 소프트웨어입니다. 쓰기 기능을 활성화하기 전에 사용 중인 카메라 모델과 펌웨어에서 반드시 테스트하십시오.

Hikvision 카메라를 안전하게 점검하고 구성할 수 있는 로컬, 기능 인지형(capability-aware) MCP 서버입니다. 현재 릴리스는 PRD의 첫 번째 엔드투엔드 수직 슬라이스를 구현합니다:

• TOML 구성 및 환경변수 기반 비밀값;

• 카메라별/도구별 권한 강제;

• 다이제스트 인증을 사용하는 비동기 ISAPI, 안전한 XML 파싱, 시간 제한적 이벤트 스트리밍;

• 카메라 식별 정보 및 기능 검색;

• 카메라의 JSON 스키마를 사용한 경고등 읽기 및 부분 구성 업데이트;

• 침입 영역, 대상, 무력화 일정, 이벤트 연동의 읽기 전용 조회;

• 모션, 변조, 라인 교차, 침입, 영역 진입/이탈, 장면 변화 규칙을 구역/일정/대상/연동과 함께 읽기 전용 조회;

• 카메라 상태, 스트림 프로필, 이미지/주야간 설정, 저장소 상태, 음향 경보 구성, 양방향 오디오 기능의 읽기 전용 조회;

• 이벤트 유형 및 활성/비활성 상태와 함께 제한된 시간 동안의 실시간 경보 모니터링;

• 필수 제안(proposal)/적용(apply) 승인 폴백;

• 충돌 감지, 검증된 재읽기(read-back), SQLite 감사/변경 이력, 롤백;

• stdio 및 로컬호스트 Streamable HTTP MCP 전송.

경고등, 외부 침입 감지, 경보 스트림 어댑터는 DS-2CD2346G2-ISU/SL 펌웨어 V5.7.14 및 V5.7.19에 대한 데이터가 정제된 픽스처 커버리지를 갖추고 있습니다. 확장된 읽기 표면에는 V5.7.19의 정제된 픽스처 커버리지가 포함됩니다. 하드웨어 쓰기는 여전히 명시적인 승인이 필요하며, 대상 장치에서 PUT/재읽기 검증 주기가 확인되기 전까지는 선택적(opt-in)으로만 허용해야 합니다. 펌웨어 간 차이는 MCP 핸들러가 아니라 어댑터 서브클래스에 속합니다.

호환성

기준 하드웨어는 DS-2CD6G2-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입니다.

안전한 변경 절차

예제 구성은 읽기 전용입니다. 이 절차를 사용하기 전에 의도적으로 서버 및 카메라 정책 상한을 모두 레벨 3로 올리십시오.

1. get_capabilities(camera="example_camera")를 호출하십시오.

2. get_warning_light를 호출하십시오.

3. configure_warning_light를 호출하십시오. 이 호출은 제안(proposal)만 생성합니다.

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과 이격(제휴)되지 않았으며 관련 엔드포스돼 있지 않습니다. Hikivision 및 ISAPI는 호환되는 제품과 프로토콜을 식별하는 데만 사용됩니다. 하드웨어 및 펌웨어 동작은 다양할 수 있으며, 지원되지 않거나 알 수 없는 기능은 추측하지 않고 친구없음_capability를 반환합니다.

버그 보고 및 기여를 환영합니다. 카메라 페이로드 또는 변경 사항을 제출하기 전에 CONTRIBUTING.md를 읽고, 취약점 신고는 SECURITY.md를 이용하십시오.

MIT License에 따라 라이선스가 부여됩니다.