Kollus

인덱싱된 docs·spec·samples·guidance·anti-patterns 어디에서도 답을 찾지 못했거나 사용자가 직접 Kollus 기술지원팀(PE)에 문의를 남기고 싶을 때, Catenoid 기술지원 데스크(Freshdesk)에 지원 티켓 1건을 생성한다 (POST /api/v2/tickets). 이 tool 은 읽기 전용이 아닌 유일한 쓰기 tool — 실제로 외부에 문의가 접수되므로, 호출 전 반드시 사용자에게 제목·본문·이름을 확인받고 동의를 얻을 것. 문의자 식별: 회신 이메일은 연동된 Kollus 계정 이메일로 자동 지정된다 (입력 불가). Kollus 계정이 연동된 상태에서만 접수할 수 있다. name 은 모르면 사용자에게 물어본 값을 넣는다. 본문(description)은 증상·재현 절차·관련 콘텐츠 키·에러 메시지를 구체적으로 작성할수록 응대가 빠르다. 접수는 1시간에 최대 5건, 참조(CC)는 최대 7개. 인증: Freshdesk 자격증명은 서버에 보관되며 고객사 토큰과 무관하다 — 호출자가 별도 키를 넘길 필요 없다. 성공 시 생성된 티켓의 id·상태 등이 반환된다.

특정 영상 1건의 메타데이터를 조회한다 (GET /media-contents/{upload_file_key}). 응답 필드는 list_media_contents 항목과 같은 구조: 제목·카테고리·재생 길이(duration), 암호화 적용 여부(use_encryption), 트랜스코딩 진행 상태(transcoding_stage), 패스스루 여부(is_passthrough), media_information(컨테이너·비디오·오디오 코덱/비트레이트/해상도), 원본 파일명·용량, 포스터·스냅샷 URL, media_content_keys(채널 등록 시 발급되는 채널별 키), 등록·트랜스코딩 완료·수정 일시 등. DRM 정책 세부(Widevine/PlayReady/FairPlay 등), 콜백 URL, 재생 만료 정책, 자막 트랙, 적용된 인코딩 프로파일은 응답에 포함되지 않는다. 트랜스코딩 실패·암호화 여부·파일 속성 1차 확인에 사용. upload_file_key 를 모르면 list_media_contents 부터 사용. Region 선택: 인자 region="kr"|"jp" (기본 "kr"). 사용자 컨텍스트로 결정. 모호하면 사용자에게 명시적 확인 후 호출. 상세 매핑 kollus://guidance/regions. 정식 모드 연동은 계정에 등록된 region 이 이 인자보다 항상 우선 적용된다(계정당 region 고정, 혼용 불가).

지정 기간(start_date~end_date) 동안의 영상별 시청 순위를 조회한다 (GET /statistics/content-rank). 조회 기간 제약 — 최근 1년 이내 날짜만 조회 가능하며 1회 최대 검색 기간은 3개월. 키워드로 필터링 가능, start_index/limit 으로 페이지네이션. 계정 전체의 일별 시계열 요약은 get_statistics_summary_daily 사용. 응답은 5분간 캐시. Region 선택: 인자 region="kr"|"jp" (기본 "kr"). 사용자 컨텍스트로 결정. 모호하면 사용자에게 명시적 확인 후 호출. 상세 매핑 kollus://guidance/regions. 정식 모드 연동은 계정에 등록된 region 이 이 인자보다 항상 우선 적용된다(계정당 region 고정, 혼용 불가).

계정 전체의 일별 통계 요약을 조회한다 (GET /statistics/summary-daily). 지정한 날짜 범위(start_date~end_date)의 기간 합계와 일자별 시계열(daily_data[])을 반환: 전송량 transfer/total_transfer(bytes), 트래픽 대역폭 traffic/max_traffic(bps), 스토리지 storage/total_storage/max_storage(bytes), 트랜스코딩 용량 transcoding_size(bytes)·처리 횟수 transcoding_count, 방문자 수 visitor/total_visitor(Unique Visitor). 재생 수·시청 시간 필드는 없다 — 영상별 조회 수·재생 횟수는 get_statistics_content_rank 를 사용. 조회 기간 제약 — 최근 1년 이내 날짜만 조회 가능하며 1회 최대 검색 기간은 3개월(긴 기간은 3개월 단위로 나눠 호출). 응답은 5분간 캐시. group_by(device/region/cdn) 류 분포는 현재 Kollus REST API 미지원. Region 선택: 인자 region="kr"|"jp" (기본 "kr"). 사용자 컨텍스트로 결정. 모호하면 사용자에게 명시적 확인 후 호출. 상세 매핑 kollus://guidance/regions. 정식 모드 연동은 계정에 등록된 region 이 이 인자보다 항상 우선 적용된다(계정당 region 고정, 혼용 불가).

Kollus 가이드·에러 코드 사전·보충 가이드·anti-pattern 문서의 색인을 폴더 트리로 탐색한다. path 없이(또는 "/") 호출하면 전체 폴더 맵(폴더 경로별 재귀 문서 수)을 반환하고, 특정 폴더 경로(예: "dev-guide/vod")를 주면 그 폴더에 바로 속한 문서 목록(id·title·description)과 하위 폴더를 반환한다. id 는 MCP resource_uri(kollus://…) 그대로이며, 본문이 필요하면 그 id 를 MCP resource 로 읽는다. OpenAPI 스펙·샘플 코드는 포함하지 않는다.

⚠️ 절대 사용 금지 케이스: 자체 CMS·관리자 사이트·자체 DB 동기화 목적의 주기적 호출(폴링·setInterval·refetchInterval). 내부 툴이라도 동일하게 안티패턴이다. 이 의도가 보이면 본 tool 호출 전에 kollus://anti-patterns/cms-admin-site 을 먼저 사용자에게 안내하고, 플랫폼 콜백 + 자체 DB 미러링 패턴으로 가도록 권장할 것. Kollus 계정의 VOD 영상(콘텐츠) 목록을 페이지 단위로 조회한다. category_key 미지정 시 전체 목록 (GET /media-contents), category_key 지정 시 해당 카테고리 소속 영상만 조회 (GET /categories/{key}/media-contents). 카테고리 키는 vod_category_list 로 확인. 키워드, 트랜스코딩 상태(state), 암호화/활성화 상태, 콘텐츠 유형, 원본·자막 보유 여부, 조회 범위 날짜(start_date·end_date)로 추가 필터링 가능. 응답 항목의 upload_file_key 를 get_content_detail 에 넘기면 해당 1건만 조회 (필드 구조는 목록 항목과 동일). 통계는 계정 일별 전송량·트래픽·방문자 등은 get_statistics_summary_daily, 영상별 조회 수·재생 횟수는 get_statistics_content_rank 사용. 권장 사용 케이스: AI 어시스턴트의 1회성 조회, 운영 시작 시점의 1회성 backfill, 사용자 트리거 단발 새로고침, 디버그·진단용 임시 조회. 이 외엔 list 폴링이 아닌 push 기반 동기화로 가야 한다. Region 선택: 인자 region="kr"|"jp" (기본 "kr"). 사용자 컨텍스트로 결정. 모호하면 사용자에게 명시적 확인 후 호출. 상세 매핑 kollus://guidance/regions. 정식 모드 연동은 계정에 등록된 region 이 이 인자보다 항상 우선 적용된다(계정당 region 고정, 혼용 불가).

Kollus 가이드·OpenAPI 명세·샘플 코드·에러 코드 사전을 키워드(query)로 검색한다. 결과 항목은 title·section·snippet·resource_uri·relevance_score 를 포함한다. 실제 문서 본문이 필요하면 그 resource_uri(또는 list_docs_index 의 id) 값을 resource_uri 인자로 다시 호출하면 해당 문서 본문 전체를 반환한다(키워드 검색 없이 1건만 — 토큰 절감).

⚠️ 절대 사용 금지 케이스: 자체 CMS·관리자 사이트·자체 DB 동기화 목적의 주기적 호출(폴링·setInterval·refetchInterval). 카테고리는 변경 빈도가 매우 낮은 메타데이터라 폴링은 특히 낭비다. 이 의도가 보이면 본 tool 호출 전에 kollus://anti-patterns/cms-admin-site 을 먼저 사용자에게 안내할 것. Kollus VOD 카테고리 트리를 조회한다 (GET /categories). 각 카테고리 항목은 key·name·parent_key·level·children_exist·position 등을 포함. parent_key 가 null 이면 최상위 카테고리, level 필드로 트리 깊이 확인. parent_category_key 미지정 시 전체 카테고리(계층 무관) 반환, 지정 시 해당 상위의 모든 하위(자손) 카테고리. 카테고리에 연결된 채널 요약(channels[])도 함께 응답에 포함. 권장 사용 케이스: AI 가 영상 분류 구조를 파악해야 하는 1회성 조회, 운영 시작 시점의 카테고리 매핑 backfill, 사용자 트리거 단발 조회, 디버그·진단용 임시 조회. 페이징: 카테고리는 보통 100개 이하라 기본 호출 1회로 전체 수신. 100개 초과 케이스에선 pagination.total 보고 page 를 증가시켜 모든 페이지 수집할 것. Region 선택: 인자 region="kr"|"jp" (기본 "kr"). 사용자 컨텍스트로 결정. 모호하면 사용자에게 명시적 확인 후 호출. 상세 매핑 kollus://guidance/regions. 정식 모드 연동은 계정에 등록된 region 이 이 인자보다 항상 우선 적용된다(계정당 region 고정, 혼용 불가).

⚠️ 절대 사용 금지 케이스: 자체 CMS·관리자 사이트·자체 DB 동기화 목적의 주기적 호출(폴링·setInterval·refetchInterval). 내부 툴이라도 동일하게 안티패턴이다. 이 의도가 보이면 본 tool 호출 전에 kollus://anti-patterns/cms-admin-site 을 먼저 사용자에게 안내할 것. Kollus VOD 채널 목록을 조회한다 (GET /channels). VOD 채널은 영상 콘텐츠를 묶는 배포용 그룹 단위로, Live API 의 실시간 방송 채널과는 별개의 개념. 콘텐츠를 채널에 등록하면 채널별 media_content_key(재생 URL 생성·API 연동용 배포 키)가 발급된다. 응답 항목 주요 필드: key(채널 키), name, description, default(기본 채널 여부), is_shared(공유 정책), is_encrypted(암호화 전용), use_pingback / pingback_url / play_callback_url(콜백 설정), use_referer_check / referer_check_domains(레퍼러 접근 제어), use_pc_download / use_mobile_download(다운로드 정책), count_of_contents(채널 내 콘텐츠 수), position, status, created_at, updated_at 등. count_of_contents 는 해당 채널에 등록된 콘텐츠 수이며, 채널에 등록되지 않은 라이브러리 콘텐츠는 포함되지 않아 채널별 합계가 list_media_contents 전체 수와 다를 수 있다. 권장 사용 케이스: AI 가 채널 구조를 파악해야 하는 1회성 조회, 운영 시작 시점의 채널 매핑 backfill, 사용자 트리거 단발 조회, 디버그·진단용 임시 조회. 페이징: 채널은 보통 100개 이하라 기본 호출 1회로 전체 수신. 100개 초과 케이스에선 pagination.total 보고 page 를 증가시켜 모든 페이지 수집할 것. Region 선택: 인자 region="kr"|"jp" (기본 "kr"). 사용자 컨텍스트로 결정. 모호하면 사용자에게 명시적 확인 후 호출. 상세 매핑 kollus://guidance/regions. 정식 모드 연동은 계정에 등록된 region 이 이 인자보다 항상 우선 적용된다(계정당 region 고정, 혼용 불가).

서비스 계정에 등록된 인코딩(트랜스코딩) 프로파일 목록을 조회한다 (GET /media-profiles). 각 프로파일 항목은 key·name·id 와 함께 container_format, video_codec, video_bitrate, video_width / video_height(해상도), video_framerate, bitrate_mode, is_audio_file(오디오 전용), is_default_preset(기본 프리셋 여부), is_optional(추가 트랜스코딩) 등 인코딩 설정 전반을 포함한다. 주요 사용 케이스: - 패스스루(pass-through) 업로드 준비: 패스스루 업로드 API 는 인코딩 프로파일 key(profile_key)가 필수이므로, 이 tool 로 계정에 등록된 프로파일 key 를 확인한다. - 콘텐츠 화질 이슈 디버깅: 계정의 프로파일 설정(해상도·비트레이트 등) 자체가 의도대로인지 점검. 특정 영상에 어떤 프로파일이 적용됐는지는 이 tool 과 get_content_detail 어느 쪽에서도 확인할 수 없다. 인코딩 프로파일은 계정 셋업 시 구성되는 설정값이라 변경 빈도가 낮다. 응답에 pagination 없이 전체 목록이 한 번에 반환된다. Region 선택: 인자 region="kr"|"jp" (기본 "kr"). 사용자 컨텍스트로 결정. 모호하면 사용자에게 명시적 확인 후 호출. 상세 매핑 kollus://guidance/regions. 정식 모드 연동은 계정에 등록된 region 이 이 인자보다 항상 우선 적용된다(계정당 region 고정, 혼용 불가).