CodePawl Video Lab

CodePawl을 위한 자체 호스팅형, 증거 우선 YouTube 분석 도구입니다. Chrome 확장 프로그램은 현재 활성화된 YouTube URL과 사용자가 직접 가져온 데이터만 수집합니다. Cloudflare Worker는 도시에와 승인된 채널 분석 데이터를 D1에 저장합니다. Codex는 무상태 Streamable HTTP MCP 서버를 통해 분석을 읽고 씁니다. 확장 프로그램 내부에는 LLM이 없습니다.

YouTube URL → Chrome side panel → Worker + D1 → /mcp → Codex
                                      ↑             │
                                      └── reports ──┘

워크스페이스

apps/extension   WXT + React MV3 side panel and library
apps/worker      Cloudflare Worker, D1, Cron, Google OAuth and remote MCP
packages/contracts  shared Zod schemas, parsers and evidence rules
docs             architecture, security and approval-gated deployment notes

확장 프로그램에는 콘텐츠 스크립트가 없습니다. 빌드된 manifest는 sidePanel, storage, activeTab, tabs를 요청합니다. YouTube DOM을 검사하거나, 캡션을 다운로드하거나, 동영상/오디오 바이트에 접근하지 않습니다.

Related MCP server: yt-mcp

로컬 개발

요구 사항: Node 22+, npm 12+, Chrome 114+.

git clone git@github.com:codepawl/codepawl-video-lab.git
cd codepawl-video-lab
npm ci
npm run cf:types
npm run db:migrate:local
npm run dev:worker
npm run dev:extension

apps/worker/.dev.vars.example을 gitignore된 .dev.vars로 복사한 후 로컬 자격 증명만 입력하세요. TOKEN_ENCRYPTION_KEY는 base64 또는 base64url로 인코딩된 32바이트 난수로 생성하세요. 로컬 개발용 Google OAuth 리디렉션 URI는 다음과 같습니다.

http://127.0.0.1:8787/oauth/youtube/callback

로컬 관리자 라우트를 통해 10분 동안 유효한 페어링 코드를 생성한 다음 사이드 패널에 입력하세요. 생성된 확장 프로그램 토큰은 30일 후 만료되며 Ngắt thiết bị로 취소할 수 있습니다.

curl -X POST http://127.0.0.1:8787/api/v1/admin/pairing-codes \
  -H "Authorization: Bearer $LOCAL_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Chrome extension"}'

압축 해제된 확장 프로그램을 빌드합니다.

npm run build --workspace @codepawl/video-lab-extension

그런 다음 개발자 모드를 활성화한 상태에서 chrome://extensions에서 apps/extension/.output/chrome-mv3을 로드하세요. 개인 Chrome 프로필에 설치하는 것은 의도적으로 수동/승인 게이트 방식의 작업입니다.

데이터 규칙

• 참조 동영상: 메타데이터와 익명화된 댓글 텍스트는 YouTube Data API v3에서 가져옵니다. 댓글은 짧은 시간 동안만 캐시되며 작성자 신원은 절대 저장되지 않습니다.

• 대본: 사용자 붙여넣기 또는 .srt, .vtt, .txt 가져오기만 허용됩니다.

• CodePawl: youtube.readonly 및 yt-analytics.readonly만 사용합니다. 업로드, 메타데이터 편집 또는 게시 범위는 존재하지 않습니다.

• Stayed to watch: 명시적 출처가 있는 수동 Studio 관찰입니다. Analytics API 측정항목으로 표현되지 않습니다.

• 참조 채널의 유지율, CTR 및 Stayed to watch는 절대 추론되지 않습니다.

• 모든 분석 결과는 출처, 관찰 시간, 신뢰도, 한계가 있는 증거를 가리켜야 합니다.

• 공개 API 데이터는 30일 후 만료됩니다. Cron은 먼저 최신 API 관찰을 시도하며, 갱신이 불가능하면 만료된 참조 데이터를 제거합니다.

• Google 갱신 토큰과 액세스 토큰은 D1에 저장되기 전에 AES-256-GCM으로 암호화됩니다.

MCP

/mcp는 D1을 기반으로 하는 무상태 createMcpHandler 서버입니다. 다음을 노출합니다.

• video_inbox_list

• video_dossier_get

• video_dossiers_compare

• channel_performance_get

• retention_curve_get

• analysis_report_save

• experiment_create

• experiment_update

리소스: codepawl://rubrics/shorts-v1.

프로덕션에서는 Cloudflare Access Managed OAuth가 /mcp를 보호합니다. Worker는 Access 어서션의 발급자, 대상, RS256 서명을 독립적으로 검증합니다. 배포 및 Access 설정을 마친 후:

codex mcp add codepawl-video-lab --url https://video-lab.codepawl.com/mcp
codex mcp login codepawl-video-lab

배포된 서버에 연결해야 하는 각 머신에서 이 두 codex mcp 명령을 실행하세요. 인증은 머신별로 이루어집니다. 자격 증명과 로컬 Codex 구성은 이 저장소에 저장되지 않습니다.

추적

Cron은 15분마다 실행되며 승인된 채널의 업로드 재생목록을 통해 업로드를 발견합니다. 새 동영상에는 2시간, 24시간, 72시간 시점의 실제 미래 목표와 일일 롤업이 지정됩니다. 과거 데이터 가져오기는 연결 시점에 초기 관찰을 받으며, 과거로 소급된 가짜 마일스톤 타임스탬프를 절대 받지 않습니다. 빈 Analytics 응답은 pending 상태를 유지하고 제한된 백오프로 재시도합니다. 작업 고유 키와 스냅샷 제약 조건 덕분에 반복 실행이 멱등성을 유지합니다.

검증

npm run typecheck
npm test
npm run build
npm run db:migrate:local
npm run worker:dry-run

시각적 픽스처는 로컬 전용입니다.

cd apps/worker
npx wrangler d1 execute video-lab --local --file test/fixtures/visual-qa.sql
cd ../..
npm run visual:dev --workspace @codepawl/video-lab-extension

http://127.0.0.1:4173/visual.html?surface=sidepanel 또는 라이브러리용 visual.html을 여세요. 이 하네스는 픽스처 데이터를 사용하며 MV3 빌드에는 포함되지 않습니다.

승인 경계

이 저장소의 설정 단계에서는 Cloudflare 리소스, DNS 레코드, Access 애플리케이션, Google OAuth 자격 증명 또는 프로덕션 배포가 생성되지 않습니다. 별도 승인이 필요한 정확한 리소스 패킷은 docs/deployment.md에서 확인하세요.

라이선스

MIT. LICENSE를 참조하세요.

주요 참고 자료

• Chrome 사이드 패널 API

• YouTube Analytics 측정항목

• YouTube API 개발자 정책

• YouTube Captions API

• Cloudflare 무상태 MCP 핸들러

• Cloudflare Access Managed OAuth

• Cloudflare Access JWT 검증

• Codex Streamable HTTP MCP