CodePawl Video Lab

Análisis de YouTube autohospedado y centrado en la evidencia para CodePawl. La extensión de Chrome recopila únicamente la URL activa de YouTube y los datos que el usuario importa deliberadamente. Un Cloudflare Worker almacena expedientes y analíticas de canales autorizados en D1. Codex lee y escribe análisis a través de un servidor MCP HTTP Streamable sin estado; no hay ningún LLM dentro de la extensión.

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

Espacio de trabajo

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

La extensión no tiene ningún script de contenido. Su manifiesto compilado solicita sidePanel, storage, activeTab y tabs; no inspecciona el DOM de YouTube, no descarga subtítulos ni accede a los bytes de video/audio.

Related MCP server: yt-mcp

Desarrollo local

Requisitos: 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

Copia apps/worker/.dev.vars.example al archivo .dev.vars (ignorado por git) y completa únicamente las credenciales locales. Genera TOKEN_ENCRYPTION_KEY como 32 bytes aleatorios codificados en base64 o base64url. El URI de redirección de OAuth de Google para el desarrollo local es:

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

Crea un código de emparejamiento de diez minutos a través de la ruta de administración local y luego introdúcelo en el panel lateral. El token de extensión resultante caduca a los 30 días y se puede revocar con 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"}'

Compila la extensión sin empaquetar:

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

A continuación, carga apps/extension/.output/chrome-mv3 desde chrome://extensions con el modo de desarrollador activado. Instalarla en un perfil personal de Chrome es, intencionadamente, una acción manual y sujeta a aprobación.

Reglas de datos

• Vídeos de referencia: los metadatos y el texto anonimizado de los cometarios provienen de la API de datos de YouTube v3. Los cometarios se almacenan en caché brevemente; la identidad del autor nunca se guarda.

• Transcripciones: solo importación mediante pegado por el usario o archivos .srt, .vtt, .txt.

• CodePawl: solo youtube.readonly y yt-analytics.readonly. No existan alcances de subida, edición de metadatos ni publicación.

• Stayed to watch: observación manual en Studio con procedencia explícita. No se representa como una métrica de la API de Analytics.

• La retención de los canales de referencia, el CTR y Stayed to watch nunca se infieren.

• Cada hallazgo debe señalar evidencia con fuente, hora de observación, confianza y limitación.

• Los datos públicos de la API caducan a los 30 días. Cron primero intenta una observación nueva de la API; los datos de referencia caducados se eliminan si la actualización no está disponible.

• Los tokens de actualización y de acceso de Google se cifran con AES-256-GCM antes de persistir en D1.

MCP

/mcp es un servidor createMcpHandler sin estado respaldado por D1. Expone:

• video_inbox_list

• video_dossier_get

• video_dossiers_compare

• channel_performance_get

• retention_curve_get

• analysis_report_save

• experiment_create

• experiment_update

Recurso: codepawl://rubrics/shorts-v1.

En producción, Cloudflare Access Managed OAuth protege /mcp; el Worker verifica de forma independiente el emisor, la audiencia y la firma RS256 de la aserción de Access. Tras el despliegue y la configuración de Access:

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

Ejecuta esos dos comandos codex mcp en cada máquina que deba conectarse al servidor desplegado. La autenticación es por máquina; las credenciales y la configuración local de Codex no se almacenan en este repositorio.

Seguimiento

Cron se ejecuta cada 15 minutos y descubre subidas a través de la lista de reproducción de subidas del canal autorizado. Los vídeos nuevos reciben objetivos futuros reales a las 2 h, 24 h y 72 h, además de resúmenes diarios. Las importaciones históricas reciben una observación inicial en el momento de la conexión y nunca reciben marcas de tiempo de hitos retroactivas falsas. Las respuestas vacías de Analytics permanecen en pending y se reintentan con retroceso limitado. Las claves únicas de las tareas y las restricciones de instantáneas hacen que las ejecuciones repetidas sean idempotentes.

Validación

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

El fixture visual es solo local:

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

Abre http://127.0.0.1:4173/visual.html?surface=sidepanel o visual.html para la biblioteca. El harness utiliza datos de fixture y no se incluye en la compilación MV3.

Límite de aprobación

La configuración de este repositorio no crea ningún recurso de Cloudflare, registro DNS, aplicación de Access, credencial de OAuth de Google ni despliegue de producción. Consulta docs/deployment.md para conocer el paquete de recursos exacto que requiere una aprobación por separado.

Licencia

MIT. Consulta LICENSE.

Referencias principales

• 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