Shaka 패키저 MCP 서버

⚠️ 실험적 상태 면책 조항
이 프로젝트는 초기 알파 단계이며 매우 실험적인 단계입니다. 실제 운영 환경에서는 사용하지 않는 것이 좋습니다. 또한, 매우 복잡할 가능성이 높습니다!
현재 제한 사항:
일관되지 않은 동작이 발생할 수 있습니다.
고급 기능(패키징, 변환 등)은 아직 활발하게 개발 중입니다.
Docker와 호스트 환경 간의 경로 변환에는 수동 구성이 필요할 수 있습니다.
빈번한 변경 사항과 잠재적 불안정성을 예상하세요
프로젝트 개선에 도움이 되도록 문제점을 알려 주시기 바랍니다.

비디오 트랜스코딩, 패키징 및 분석을 위해 Shaka Packager 와 Claude AI 애플리케이션을 통합하는 MCP(Model Context Protocol) 서버입니다.

이 서버는 파일 시스템 MCP 서버 와 함께 작동하여 Claude Desktop이 사용자 컴퓨터의 비디오 파일에 액세스하고 처리할 수 있도록 하며, Claude를 미디어 처리 작업을 위한 강력한 도우미로 만들어줍니다.

특징

비디오 분석 : 비디오 파일을 분석하여 자세한 스트림 정보, 코덱, 비트 전송률 등을 추출합니다.
미디어 패키징 : VOD 및 라이브 스트리밍을 지원하여 HLS 및 DASH 형식으로 스트리밍할 비디오를 변환합니다.
고급 옵션 :
- DRM 암호화 적용(Widevine, PlayReady, FairPlay)
- 광고 삽입 마커 구성
- 포맷(MP4, TS 등) 간 변환
지능형 경로 처리 : Docker와 호스트 환경 간의 경로를 자동으로 변환합니다.
강력한 오류 관리 : 해결을 위한 제안과 함께 의미 있는 오류 분석을 제공합니다.
명령 지원 : 최적의 결과를 위해 Shaka Packager 명령을 올바르게 형식화하는 데 도움이 됩니다.
대화형 문서 : 복잡한 작업을 안내하는 기본 제공 도움말 및 예제
자세한 출력 : 모든 작업에 대한 포괄적인 요약 및 실행 세부 정보

필수 조건

Python 3.10 이상
Shaka Packager가 설치되어 PATH에 사용 가능합니다.
- GitHub에서 다운로드
- 또는 다음 지침 에 따라 소스에서 빌드하세요.
MCP 호환 클라이언트(Claude Desktop 등)

설치

pip 또는 uv 사용(곧 제공)

pip로 패키지를 설치하세요:

지엑스피1

또는 uv를 사용하여:

uv pip install shaka-packager-mcp

출처에서 (추천)

git clone https://github.com/coderjun/shaka-packager-mcp.git
cd shaka-packager-mcp
pip install -e .

또는 uv를 사용하여:

git clone https://github.com/coderjun/shaka-packager-mcp.git
cd shaka-packager-mcp
uv pip install -e .

Claude 데스크톱 통합

Claude Desktop은 비디오 파일 업로드를 직접 지원하지 않으므로 두 서버 접근 방식을 사용합니다.

컴퓨터의 비디오 파일에 액세스하기 위한 간소화된 파일 시스템 MCP 서버
Shaka Packager MCP 서버는 해당 비디오를 분석하고 처리합니다.

1단계: MCP 파일 시스템 서버 설정

Claude가 비디오 파일에 액세스할 수 있도록 하려면 공식 MCP 파일 시스템 서버를 사용하세요.

Docker로 공식 파일 시스템 서버를 설치하세요:
docker pull mcp/filesystem
또는 Filesystem MCP Server 저장소의 지침에 따라 소스에서 빌드할 수 있습니다.

2단계: 구성 파일 찾기

Claude Desktop 구성 파일을 찾으세요.

macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
윈도우 : %APPDATA%\Claude\claude_desktop_config.json

파일이 없으면 만듭니다.

3단계: 두 서버를 구성에 추가

다음 구성을 추가하고 절대 경로를 사용하세요.

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/PATH/TO/VIDEOS/DIRECTORY,dst=/projects/video-drop",
        "mcp/filesystem",
        "/projects"
      ]
    },
    "shaka-packager": {
      "command": "/ABSOLUTE/PATH/TO/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "/ABSOLUTE/PATH/TO/shaka_packager_mcp.py"
      ],
      "env": {
        "VIDEO_PATH": "/PATH/TO/VIDEOS/DIRECTORY",
        "SHAKA_PACKAGER_PATH": "/PATH/TO/PACKAGER"
      }
    }
  }
}

바꾸다:

/PATH/TO/VIDEOS/DIRECTORY 에 비디오 파일이 있는 디렉토리 경로를 추가합니다.
uv 실행 파일의 전체 경로를 포함하는 /ABSOLUTE/PATH/TO/uv
스크립트 파일에 대한 전체 경로를 포함하는 /ABSOLUTE/PATH/TO/shaka_packager_mcp.py
Shaka Packager 실행 파일의 전체 경로를 포함하는 /PATH/TO/PACKAGER

예를 들어:

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Videos,dst=/projects/video-drop",
        "mcp/filesystem",
        "/projects"
      ]
    },
    "shaka-packager": {
      "command": "/Users/username/.local/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "/Users/username/Development/shaka-packager-mcp/shaka_packager_mcp.py"
      ],
      "env": {
        "VIDEO_PATH": "/Users/username/Videos",
        "SHAKA_PACKAGER_PATH": "/Users/username/.shaka/packager"
      }
    }
  }
}

4단계: Claude Desktop을 다시 시작하세요

구성 파일을 편집한 후 Claude Desktop을 다시 시작하여 변경 사항을 적용합니다.

2서버 접근 방식을 사용하는 방법

먼저, 간소화된 파일 시스템 서버를 사용하여 비디오 파일을 탐색하세요.
- Claude에게 "내 비디오 디렉토리에 있는 파일 나열"을 요청하세요.
- 분석하거나 처리하려는 비디오 파일로 이동합니다.
비디오 파일을 찾았으면 Shaka Packager 도구를 사용하여 해당 경로를 사용하세요.
- 분석용: "이 비디오를 분석해 주세요: /Users/username/Videos/example.mp4"
- 처리용: "이 비디오를 HLS용으로 패키징해 주세요: /Users/username/Videos/example.mp4"

문제 해결

문제가 발생할 경우:

두 서버 모두 절대 경로로 올바르게 구성되었는지 확인하세요.
Shaka Packager가 설치되었고 접근 가능한지 확인하세요.
파일 시스템 서버에 지정된 디렉토리가 존재하고 비디오가 포함되어 있는지 확인하세요.
Claude Desktop 로그에서 오류를 확인하세요.
- macOS: ~/Library/Logs/Claude/mcp*.log
- Windows: %APPDATA%\Claude\logs\mcp*.log

용법

Claude Desktop에서 Filesystem MCP 서버와 Shaka Packager MCP 서버가 모두 실행되면:

비디오 파일에 접근하세요 :
Please show me the files in my Videos directory
비디오 파일로 이동합니다 .
Please show me the files in the Movies subdirectory
처리하려는 비디오의 file:// URI 경로를 복사하세요.
Shaka Packager 도구를 파일 경로와 함께 사용하세요 :
Please analyze this video: file:///Users/username/Videos/my_video.mp4
또는
Please package this video for HLS and DASH streaming: file:///Users/username/Videos/my_video.mp4
서버는 적절한 Shaka Packager 명령을 실행하고 결과에 대한 자세한 요약을 제공합니다.

비디오 파일의 정확한 위치를 알고 있다면 직접 파일 경로를 사용할 수도 있습니다.

Please analyze this video: /Users/username/Videos/my_video.mp4

도구

서버는 다음과 같은 도구를 제공합니다.

analyze_video : 비디오 파일을 검사하고 지능적인 오류 처리 기능을 통해 자세한 스트림 정보를 제공합니다.
run_shaka_packager : 사용자 정의 인수와 적절한 경로 처리를 사용하여 모든 Shaka Packager 명령을 실행합니다.
get_shaka_options : 사용 가능한 명령 옵션과 버전 정보를 검색합니다.
get_shaka_documentation : Shaka Packager 사용에 대한 포괄적인 설명서와 예제를 제공합니다.

프롬프트

서버에는 다음과 같은 프롬프트 템플릿이 포함되어 있습니다.

MP4에서 TS로 변환
HLS 및 DASH의 VOD 패키징
라이브 스트리밍 패키징
콘텐츠 암호화
광고 삽입 준비
비디오 분석
명령어 형식 알림
오류 해석 안내

구성

서버는 환경 변수를 사용하여 구성할 수 있습니다.

SHAKA_PACKAGER_PATH : Shaka Packager 실행 파일의 경로(Claude Desktop에 강력히 권장)
VIDEO_PATH : 로컬 비디오 디렉토리 경로(Docker와 호스트 간 경로를 변환하는 데 사용됨)
DOCKER_PATH : Docker 컨테이너 마운트 경로(기본값: "/projects/video-drop")
TEMP_DIR : 파일 업로드를 위한 사용자 정의 임시 디렉토리
LOG_LEVEL : 로깅 레벨(DEBUG, INFO, WARNING, ERROR, CRITICAL)
COMMAND_TIMEOUT : Shaka Packager 명령에 대한 시간 초과(초)(기본값: 300)

다음에서 설정할 수 있습니다.

Claude Desktop 구성 파일( SHAKA_PACKAGER_PATH 및 VIDEO_PATH 에 권장됨)
환경 변수
스크립트와 같은 디렉토리에 있는 .env 파일

.env 파일 예시:

SHAKA_PACKAGER_PATH=/usr/local/bin/packager
VIDEO_PATH=/Users/yourusername/Videos
LOG_LEVEL=DEBUG

개발

개발 환경 설정

# Clone the repository
git clone https://github.com/coderjun/shaka-packager-mcp.git
cd shaka-packager-mcp

# Install development dependencies with pip
pip install -e ".[dev]"

# Or with uv
uv pip install -e ".[dev]"

테스트 실행

pytest

코드 포맷팅

black .
isort .

코드 구조 이해

Shaka Packager MCP 서버의 주요 구성 요소는 다음과 같습니다.

shaka_packager_mcp.py : MCP 도구 및 프롬프트를 사용한 메인 서버 구현
tests/ : 기능을 검증하기 위한 테스트 모음

이 서버는 공식 MCP 파일 시스템 서버와 함께 작동하여 비디오 파일에 액세스하도록 설계되었습니다.

구현의 주요 기능

강력한 경로 처리 : Docker와 호스트 환경 간의 경로를 자동으로 변환합니다.
스마트 오류 처리 : 의미 있는 오류 메시지와 제안을 제공합니다.
명령 구문 지원 : Shaka Packager 명령을 올바르게 형식화하는 데 도움이 됩니다.
문서 통합 : 포괄적인 문서 및 예제 제공

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

도움 받기

AI 코드 조종사를 사용해도 괜찮습니다. 저자는 그렇게 합니다.

문제가 발생하거나 질문이 있는 경우:

이 README의 문제 해결 섹션을 확인하세요.
Shaka Packager 문서를 검토하세요
Claude 내에서 대화형 도움말을 보려면 get_shaka_documentation 도구를 사용하세요.
GitHub에 이슈를 열어보세요

감사의 말

강력한 비디오 처리 기능을 위한 Shaka Packager
통신 프레임워크를 위한 모델 컨텍스트 프로토콜(MCP)
AI 보조 기능을 위한 Claude
클로드와 MCP 표준 개발을 위한 인류학적

Shaka Packager MCP Server

Integrations