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

この拡張機能にコンテンツスクリプトはありません。ビルド済みマニフェストが要求するのは 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日後に失効し、デバイスを切断 で取り消すことができます:

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"}'

unpacked拡張機能をビルドします:

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

デプロイされたサーバーに接続する各マシンで、その2つの 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 Side Panel API

• YouTube Analytics metrics

• YouTube API developer policies

• YouTube Captions API

• Cloudflare stateless MCP handler

• Cloudflare Access Managed OAuth

• Cloudflare Access JWT validation

• Codex Streamable HTTP MCP