axis-camera-mcp

LLM(Claude Code/Desktop)이 VAPIX(Axis의 HTTP/JSON 카메라 API)를 통해 Axis 네트워크 카메라와 통신할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다. VLC에서 라이브 스트림 보기, 팬/틸트/줌 제어, 이미지 센서 설정(밝기, 노출, 게인, 화이트 밸런스) 조정, 스냅샷 캡처, 텍스트/이미지 오버레이 추가, 시계 설정/조회, 로컬 카메라 사용자 계정 관리, 조명 제어를 지원합니다.

로컬 네트워크의 AXIS M3057-PLVE Mk II를 대상으로 빌드 및 실기기 검증을 완료했습니다. 실제로 라이브 테스트된 항목과 그렇지 않은 항목은 docs/live-verification-checklist.md를 참조하고, 이 특정 카메라의 확인된 제한 사항은 docs/open-questions.md를 참조하세요. PTZ 명령은 성공하고 보고된 위치는 업데이트되지만, 이 고정 카메라 모델에서는 실제 시각적 팬/틸트/줌 효과가 발생하지 않습니다.

아키텍처

axis_camera_mcp/
  config.py            Loads camera host/username/password from config.json
  vapix/
    session.py          requests.Session + HTTP Digest auth
    jsonrpc.py           Client for VAPIX's modern JSON-RPC-style APIs
    legacy.py             Client for VAPIX's legacy query-param/plain-text CGIs
    client.py              VapixClient facade - the only thing tools/* imports
    exceptions.py
  vlc_launcher.py       Starts/stops the local VLC install to view the RTSP stream
  rag/                  Local knowledge base: VAPIX docs + this project's own
                        live-verified findings, hybrid BM25+embedding search
                        (see "Knowledge base (RAG)" below)
  app.py / context.py  Shared FastMCP instance + lazy VapixClient/VlcLauncher/
                        HybridRetriever singletons
  tools/                One module per capability, each registering @mcp.tool()s
  server.py             Entrypoint: import tools, preload_rag(), mcp.run()
tests/
  test_*.py             Unit tests, mocked HTTP, no live camera needed
  manual/                Plain scripts (not pytest) exercised against the real camera
docs/
  live-verification-checklist.md   One row per tool - what's actually been tested live
  open-questions.md                Confirmed limitations and things not yet tried

이 카메라에는 두 가지 VAPIX 요청 스타일이 공존하며, 클라이언트 계층은 이 차이를 도구 코드에 노출하지 않고 두 가지를 모두 처리합니다.

• 최신 JSON-RPC 스타일 (api-discovery, basicdeviceinfo, streamprofile, lightcontrol, time.cgi, dynamicoverlay): JSON 본문 {"apiVersion", "method", "params"}을 POST하고, 응답은 {"data"} 또는 {"error"}입니다.

• 레거시 쿼리 매개변수/일반 텍스트 CGI (com/ptz.cgi, com/ptzconfig.cgi, pwdgrp.cgi, usergroup.cgi, jpg/image.cgi): 쿼리 매개변수가 있는 일반 GET이며, 응답은 일반 텍스트(때로는 key=value 줄) 또는 스냅샷 엔드포인트의 경우 원시 JPEG 바이트입니다.

설정

자격 증명은 코드나 환경 변수가 아닌 구성 파일에 저장됩니다:

copy config.example.json config.json
notepad config.json   # fill in host/username/password

config.json은 gitignore 처리되어 커밋되지 않습니다.

py -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"

실행

.venv\Scripts\python -m axis_camera_mcp.server

지식 베이스(RAG)

로컬 오프라인 지식 베이스를 통해 LLM은 실제 VAPIX API 문서와 이 프로젝트의 직접 검증된 결과(문서화되지 않은 필수 필드, 라이브 시행착오를 통해서만 확인된 실제 매개변수 값 등)를 매번 추측하거나 다시 유도하는 대신 검색할 수 있습니다.

모두 오픈소스, 모두 로컬 - 유료 API나 벡터 DB 서비스가 없습니다:

• 크롤러 (rag/crawler.py): developer.axis.com(서버 렌더링 Docusaurus 사이트 - 헤드리스 브라우저 불필요)에 대해 일반 requests + BeautifulSoup을 사용하며, 이 프로젝트의 자체 README/docs/vapix/*.py를 로컬 소스로 사용합니다.

• 청킹 (rag/chunker.py): 문단 인식, 약 700자, 100자 오버랩.

• 검색 (rag/retriever.py): 하이브리드 - BM25(rank-bm25, streamProfileName 같은 정확한 키워드 일치)와 밀집 임베딩(sentence-transformers, all-MiniLM-L6-v2, CPU 전용, 의역 질문용)을 상호 순위 융합으로 결합합니다. 일반 numpy .npz 파일이 벡터 저장소 역할을 합니다(수백 개의 청크는 무차별 코사인 검색을 마이크로초 단위로 만들므로 실제 벡터 DB 의존성이 필요 없습니다).

• 추적 (rag/tracking.py): 로컬 SQLite 파일이 모든 수집 실행(소스별 청크/문자 수, 성공/오류 상태)과 모든 쿼리(텍스트, 결과, 점수)를 기록합니다. 직접 또는 rag_stats 도구를 통해 검사할 수 있습니다.

설정: sentence-transformers는 torch를 끌어오는데, 이는 상당히 무거운 설치입니다. CPU 전용 머신에서는 기본 해결 빌드보다 훨씬 작게 유지하기 위해 먼저 CPU 전용 휠을 명시적으로 설치하세요:

.venv\Scripts\python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
.venv\Scripts\python -m pip install -e ".[dev]"

인덱스 빌드/새로 고침 (별도의 수동 실행 단계 - 서버 시작 시 자동으로 실행되지 않으므로 시작이 빠르고 네트워크 호출이 없습니다):

.venv\Scripts\python -m axis_camera_mcp.rag.ingest

axis_camera_mcp/rag/sources.json을 편집하여 문서 페이지나 로컬 파일을 추가/제거한 후 위 명령을 다시 실행하세요. 임베딩 모델(약 80MB)은 첫 실행 시 Hugging Face Hub에서 한 번 다운로드된 후 캐시됩니다. 그 외 모든 것은 완전히 오프라인입니다. 생성된 인덱스 파일(rag/data/*.jsonl, *.npz, *.sqlite3)은 gitignore 처리됩니다.

search_knowledge 및 rag_stats 도구로 쿼리할 수 있습니다(아래 도구 참조 참조).

Claude Code/Desktop에 등록

{
  "mcpServers": {
    "axis-camera": {
      "command": "<path-to-repo>\\.venv\\Scripts\\python.exe",
      "args": ["-m", "axis_camera_mcp.server"]
    }
  }
}

이 항목을 추가한 후 도구가 나타나도록 Claude Code/Desktop을 다시 시작하세요.

테스트

.venv\Scripts\python -m pytest tests/ --ignore=tests/manual   # unit tests, mocked HTTP
.venv\Scripts\python tests/manual/live_smoke_test.py           # read-only checks against the real camera

tests/manual/ 스크립트는 config.json의 실제 카메라와 통신합니다. 중요하게 생각하는 카메라에 대해 실행하기 전에 각 스크립트가 수행하는 작업을 검토하세요. live_smoke_test.py는 읽기 전용입니다. mcp_harness_*.py 스크립트는 전체 MCP 도구 호출 경로(PTZ 이동, 시계/시간대 변경, 사용자 추가/제거와 같은 변경 작업 포함)를 실행합니다. 이는 이 프로젝트의 자체 실기기 검증 스크립트였으므로 참조용으로 취급하고 프로덕션 카메라에 무심코 다시 실행하지 마세요.

도구 참조

장치/API 정보 (읽기 전용): get_device_info, get_supported_apis, get_camera_overview

스트리밍 (로컬 VLC 설치에서 라이브 스트림 보기): start_stream, stop_stream, get_stream_status, list_stream_profiles

스냅샷 (비디오 스트림과 별개의 단일 정지 프레임): save_snapshot (파일만 저장, LLM은 이미지를 볼 수 없음), get_snapshot (LLM에 직접 반환되어 화면에 무엇이 있는지 설명할 수 있음)

PTZ (팬/틸트/줌 - 이 특정 카메라에서 시각적 효과가 없다는 점은 docs/open-questions.md 참조): ptz_move_absolute, ptz_move_relative, ptz_get_position, ptz_save_preset, ptz_goto_preset, ptz_list_presets

이미지 센서 (밝기/대비/채도/선명도, 노출, 게인, 셔터, 화이트 밸런스 - PTZ의 프레이밍/크롭 및 조명의 물리적 조명기와 구별되는 실제 센서/ISP 설정): get_image_settings, set_image_appearance, set_exposure_mode, set_exposure_value, set_manual_gain, set_manual_shutter, set_white_balance

오버레이 (비디오 스트림에 합성되는 텍스트/이미지): add_text_overlay, set_text_overlay, add_image_overlay, set_image_overlay, list_overlays, remove_overlay, get_overlay_capabilities

시계: get_clock_info, set_clock, set_timezone

조명 (이 특정 카메라에는 조명 하드웨어가 없음 - get_light_status로 확인되며 명확히 보고됨): get_light_status, activate_light/deactivate_light, enable_light/disable_light, set_light_intensity, get_valid_intensity, set_light_auto_mode

사용자 - 변경 작업에는 confirm: true가 필요하며, 실제 보안 영향이 있는 유일한 영역입니다: list_users (권한 있는 호출자에게 모든 계정과 권한 그룹을 반환), add_user, update_user, remove_user

지식 베이스 (위의 "지식 베이스(RAG)" 참조): search_knowledge (VAPIX 문서 및 이 프로젝트의 실기기 검증 결과에 대한 하이브리드 BM25+임베딩 검색, 소스 인용 및 점수 포함), rag_stats (인덱스된 내용, 출처, 시기, 최근 쿼리 기록 - 인덱스에 rag.ingest 실행이 필요한지 명확히 표시)

안전

사용자 계정 변경 작업(add_user, update_user, remove_user)은 명시적인 confirm: true 도구 인수가 필요하며, 없으면 명확한 오류를 발생시킵니다. 이는 부주의한 호출이 실제 보안 영향(무단 액세스 또는 우발적 잠금)을 미칠 수 있는 유일한 영역입니다. 그 외 모든 것(PTZ, 조명, 시계, 스트리밍, 오버레이, 스냅샷)은 설계상 확인 없이 실행됩니다. 자유롭게 되돌릴 수 있고 사용자가 직접 소유한 단일 카메라이며 공유 프로덕션 시스템이 아니기 때문입니다.