Slashloop MCP

slashloop

面向病毒式短视频研究的托管 MCP 服务——追踪 TikTok / Reels / Shorts 来源，查找异常表现的视频，运行 Gemini 视频分析，并将 热门视频转化为吸睛开场、创意和创意简报。

仅支持远程 HTTP MCP（无本地 stdio 服务）：托管于 Cloudflare Workers（D1 + R2 + KV + Cron Triggers），在切换到原生 IdP 之前通过 Supabase OAuth2 进行身份验证。切换稳定期内，Vercel + Supabase Postgres 仍作为 旧版／回滚后端（参见 docs/cf-full-backend-plan.md）。API 密钥（Gemini、抓取代理）保存在服务端， 因此安装者无需处理这些密钥。

界面	位置	安装	客户端
Claude 插件	claude-plugin/	/plugin marketplace add man0l/slashloop	Claude Code
连接器	已部署主机	将 …/mcp 添加为自定义连接器	Claude Desktop、Cowork、claude.ai

在线端点：https://mcp.slashloop.dev/mcp

Agent 技能

skills/ 包含适用于远程 MCP 的可安装 Agent 技能： slashloop-sources、slashloop-refresh、slashloop-gallery、 slashloop-experiments 和 slashloop。发布到 npm 后，请通过以下方式安装：

npx slashloop-skills install --codex

如需使用其他技能根目录，请使用 --claude、--project 或 --target <skills-dir>。 将技能目录复制到 Agent 的技能根目录（对于 Codex， 为 $CODEX_HOME/skills），并在运行工作流前阅读其中的 SKILL.md。 每项技能都要求指定工作区 ID 或准确的工作区名称；不会有任何技能 静默地默认使用主工作区。

src/
  register-tools.ts  # 63 tools, shared with the remote host
  tools/             # sources, feed, video, hooks, creative, studio, settings, experiments
  analysis/          # Gemini native + text analyzers
  lib/               # scrapers, gemini, spend-cap, storage, media, retention
remote/              # OAuth + Streamable HTTP handlers
api/                 # Legacy Vercel entrypoints, retained as the rollback path.
                     # Several URL paths were folded onto one physical function
                     # via rewrites (see api/sources.ts); that rewrite config
                     # went away with the Vercel project. Live routing is
                     # src/cf/router.ts, which mirrors the old rewrites 1:1.
api/billing.ts       # Checkout, Billing Portal, status — called by slashloop-site
api/stripe/          # Webhook — the only thing that grants/revokes credits
api/cron/            # Scheduled jobs (media retention sweep, weekly digest)
claude-plugin/       # Claude Code plugin (skills + bundled remote MCP)

---

安装

Claude Code（插件——技能 + 远程 MCP）

/plugin marketplace add man0l/slashloop

然后从 Marketplace 标签页安装 slashloop。该插件会注册 远程 MCP 服务和 /slashloop:track、/slashloop:discover 技能。 首次调用工具时，请在浏览器中完成 Supabase OAuth 登录。

Claude Desktop / Cowork / claude.ai（连接器）

Settings → Connectors → Add custom connector → https://mcp.slashloop.dev/mcp → 登录 → 授权。 随后即可使用全部 63 个工具（以及 whoami）；可用自然语言提问 （“追踪 TikTok 创作者 @x”、“查找关于 Y 的异常表现视频”）。

/slashloop:track / /discover 斜杠快捷指令是 Claude Code 插件 技能。在 Desktop/Cowork 中无需使用它们——连接器会直接提供所有 工具。

---

自托管（Workers 为主；Vercel + Supabase 为旧版／回滚方案）

正在进行切换：Worker + D1 是主方案（docs/cf-full-backend-plan.md、 操作手册 docs/cloudflare-migration.md、检查清单 docs/cf-cutover-checklist.md）。 以下为旧版 Vercel/Supabase 方案，保留作回滚目标。

Vercel 项目已删除，因此目前无法部署该方案：下方的 vercel --prod 需要重新创建项目，vercel.json（api/ 入口所依赖的 URL 重写配置） 也已随项目一同删除。api/ 源码和 Supabase 步骤仍保留在此， 以便恢复该方案。

1. Supabase 控制面板

1. Auth → URL Configuration → Site URL = 你的公开连接器 URL。
2. Auth → OAuth Server → Enable。授权路径 = /oauth/consent。 开启 Dynamic client registration。
3. JWT signing → asymmetric (RS256)。
4. 启用 Email/password，并创建一个用户。

2. 环境变量

cp .env.example .env
# DATABASE_URL + DIRECT_URL (Supabase Postgres pooler)
# SUPABASE_URL, SUPABASE_ANON_KEY
# GEMINI_API_KEY, SCRAPER_PROXY_URL, PROXY_TRAFFIC_CAP_GB, PUBLIC_URL

3. 运行／部署

bun install
bun run remote:dev       # local: http://localhost:8788 (+ tunnel for OAuth)
# or: vercel --prod

架构变更

生产环境架构由 Supabase 迁移管理，而非 Prisma。 合并到 默认分支后，supabase/migrations/ 中的 SQL 文件会通过 Supabase GitHub 集成应用。 prisma/schema.prisma 仍是 客户端（类型 + 查询构建器）的事实来源—— 两者必须手动保持同步。

添加架构变更：

# 1. Edit prisma/schema.prisma
# 2. Generate the delta SQL (offline — no DB connection needed):
bunx prisma migrate diff \
  --from-schema-datamodel <schema.prisma before your change> \
  --to-schema-datamodel   prisma/schema.prisma \
  --script > supabase/migrations/$(date +%Y%m%d%H%M%S)_your_change.sql
# 3. Harden it with IF NOT EXISTS guards (see the billing migration for the
#    pattern), commit, and merge — Supabase applies it.
bun run db:generate      # refresh the Prisma client

媒体存储（可选）

TikTok 封面图片和 MP4 文件会持久保存到 Supabase Storage，这样即使源 CDN 的签名 URL 过期，动态也不会显示为损坏的图片；重新分析时也可以跳过按量计费的代理下载。若不设置 SUPABASE_SECRET_KEY，整条流程都会停用，其他一切照常运行。

只需完成一步设置：在 Vercel 中设置 SUPABASE_SECRET_KEY 和 CRON_SECRET。需要两个存储桶：**thumbs（公开，5MiB，仅限图片）**和 media（私有，100MiB，仅限 video/mp4）。 supabase/migrations/*_media_storage_buckets.sql 会在存储桶不存在时创建它们，因此新项目或本地运行 supabase start 后即可使用。

此迁移仅会创建（ON CONFLICT DO NOTHING），不会调整已存在的存储桶，因此不会影响仪表板中的设置。如果对 storage.buckets 的权限操作失败，它也会将错误降级为 NOTICE，而不会阻止部署。

因此，对于手动创建存储桶的项目（包括本项目），上述大小限制和 MIME 类型允许列表并不存在，也不会因部署而添加。在仪表板中创建的存储桶默认没有限制，除非有人手动设置。没有这些限制也不会出问题；它们只是上限，并非必需条件。若要实际启用这些限制，请在仪表板中设置。

真正重要的是：media 必须设为私有，否则抓取的视频就会被公开镜像。建议确认一次。

保留期限默认为 3 天，是一项按工作区设置的选项，可通过 update_settings 工具更改，但会受套餐限制。Supabase 没有对象生命周期规则，因此过期清理会通过每日运行的 Vercel Cron（/api/cron/media-retention）执行。

分析在请求路径之外运行

使用 gemini-native 后端的 analyze_video 会排队而非内联分析，并返回一个 jobId。轮询 get_video：analysisJob 会报告进度，分析完成后，结果会出现在 analysis 中。gemini-text 仍会直接返回分析结果；它只需进行一次文本调用，几秒内即可完成。

这是由硬性限制决定的，而非偏好：原生分析必须下载 MP4、将其上传到 Gemini、等待处理，然后生成结果，这无法在 api/mcp.ts 的 60s maxDuration 内完成，而且 Vercel 套餐不允许提高此上限。MCP 客户端也有自己的超时，因此即使服务器预算更大，同步调用也无法挽救。

入队时会向 /api/jobs/analyze 发起非阻塞调用，由它在一次全新的调用中运行任务，并有自己的 60s 时限。此调度尽力而为，不会有任何操作依赖它。

队列可靠性的保障来自在 Postgres 内每分钟运行的 pg_cron（supabase/migrations/*_pgcron_drain_analyze_jobs.sql）。此套餐将 Vercel Cron 限制为每天运行一次，并会在部署时拒绝低于每天一次的表达式；而 pg_cron 完全不受此限制。它每分钟都会向 /api/jobs/analyze 发送 POST 请求，但仅当有一行状态为 queued 或 running 时才会发送，因此队列空闲时不会产生函数调用。

任务不会做其他事：由 TypeScript 中的工作器负责恢复已放弃的认领，这样 MAX_ATTEMPTS 和 STUCK_AFTER_MINUTES 只需定义一次（src/lib/jobs.ts），而不必在 SQL 中维护第二份容易发生偏差的副本。闸门中包含 running，因为只有工作器才能判断某个认领是否已被放弃。

Supabase Vault 中必须存在两个密钥，否则该任务会有意地空操作：

Vault 密钥	值
cron_secret	必须与工作器检查的 CRON_SECRET 环境变量相同
worker_base_url	例如 https://mcp.slashloop.dev，末尾不要加斜杠

这些密钥会在运行时按名称读取，不在迁移文件中。如果你在 Vercel 中轮换了 CRON_SECRET，也要更新 Vault 中的副本，否则清理请求会静默返回 401。

我们有意不为此设置 Vercel Cron 回退方案。每分钟运行一次的任务再加上一个每天运行一次的副本，会形成第三条代码路径，只有在 pg_cron 故障时才派得上用场，而且它会掩盖故障，而不是暴露故障。如果清理任务停止，queued 中的任务会明显堆积——这正是你需要的信号。

完整设计（包括后续阶段）：docs/media-storage-plan.md。

⚠️ 不要对生产环境运行 bun run db:push。 它会完全绕过迁移历史，并导致数据库状态偏离 Supabase 已应用的内容。 它仅用于一次性本地数据库。同样，绝不要运行 prisma migrate——它会维护自己的 _prisma_migrations 表，而 Supabase 对此一无所知。

路由

路由	用途
POST /mcp	MCP 端点（Bearer JWT）
GET /.well-known/oauth-protected-resource	RFC 9728 → Supabase AS
GET /login	电子邮件/密码登录
GET /oauth/consent	授权界面
GET /health	存活状态
POST /api/billing/checkout	Bearer JWT。创建 Stripe Checkout Session，返回 { url }
POST /api/billing/portal	Bearer JWT。创建 Billing Portal 会话，返回 { url }
GET /api/billing/status	Bearer JWT。返回 { planKey, planCredits, packCredits, periodEnd, billingStatus }
POST /api/stripe/webhook	Stripe 签名，而非 JWT。唯一可授予/撤销额度的接口
POST /api/jobs/analyze	CRON_SECRET。在请求路径之外处理排队的分析任务
GET /api/cron/media-retention	CRON_SECRET。每日运行。使存储的媒体过期

三个 /api/billing/* 路由均为 SITE_URL（落地页网站的源）配置了 CORS；/mcp 和 /api/stripe/webhook 不需要，因为两者都不会从浏览器调用。

---

必需变量

变量	是否必需？	用途
DATABASE_URL	是	Supabase Postgres 连接池（?pgbouncer=true&connection_limit=1）
DIRECT_URL	仅本地	Supabase 会话模式 URL（端口 5432）。Prisma 的数据源声明了此变量，但生产环境的架构变更通过 supabase/migrations/ 进行——参见上文“架构变更”
SUPABASE_URL	是（远程）	https://YOUR-PROJECT.supabase.co
SUPABASE_ANON_KEY	是（远程）	Supabase 可公开密钥
GEMINI_API_KEY	是	为 gemini-native（主要）和 gemini-text（备用）分析、钩子变体及简报提供支持
SCRAPER_PROXY_URL	用于实时 TikTok	用于列表抓取和单视频下载的住宅代理
PROXY_TRAFFIC_CAP_GB	可选	每月代理流量上限，以网络传输字节数计，即压缩数据加标头（默认值为 0.25）
PUBLIC_URL	是（生产环境）	Claude 可访问的公共源
SITE_URL	是（计费）	slashloop-site 的源——Checkout/Portal 重定向和 CORS
STRIPE_MODE	否（默认值为 live）	live 或 test——应用使用哪组密钥
STRIPE_SECRET_KEY / STRIPE_TEST_SECRET_KEY	是（计费）	Stripe 实时 / 测试 API 密钥
STRIPE_WEBHOOK_SECRET / STRIPE_TEST_WEBHOOK_SECRET	是（计费）	/api/stripe/webhook 的实时 / 测试签名密钥
STRIPE_PRICE_* / STRIPE_TEST_PRICE_*	是（计费）	实时 / 测试 Price ID（CREATOR_MONTH、CREATOR_YEAR、PRO_MONTH、PRO_YEAR、PACK）。在 Cloudflare Worker 上，这些变量会以一个 STRIPE_PRICES JSON 绑定项的形式提供（以这些名称为键，由 sync-worker-secrets.mjs 构建）；每个名称对应的变量仍作为备用方案保留
SUPABASE_SECRET_KEY	可选	启用媒体存储。未设置时，整个媒体流程都不会执行任何操作
STORAGE_THUMB_BUCKET / STORAGE_MEDIA_BUCKET	可选	存储桶名称（默认值分别为公开的 thumbs 和私有的 media）
THUMB_RETENTION_DAYS_DEFAULT / MEDIA_RETENTION_DAYS_DEFAULT	可选	仅为新工作区设置初始值（默认值为 3）。保留时长本身是每个工作区的设置
RETENTION_DAYS_MAX	可选	超出任何套餐限额的绝对上限（默认值为 90）
CRON_SECRET	是（存储）	保护 /api/cron/*。保留期清理任务会删除媒体，因此不得允许公众调用

完整的 Stripe 控制面板设置（产品、价格、Webhook 注册）请参阅 docs/stripe-implementation-plan.md。合并时通过 Supabase 迁移 supabase/migrations/ 应用架构；剩下的手动步骤是 使用真实 Stripe 账户中的值填充上述环境变量。

---

工具清单（63 个工具，另有远程主机上的 whoami）

模块	工具
Sources（8 个）	list_sources, get_source, create_source, update_source, delete_source, refresh_source, suggest_sources, dismiss_suggested_source
Discover（1 个）	discover
Feed（3 个）	get_feed, search_library, get_outlier_summary
Video（3 个）	get_video, analyze_video, get_video_transcript
Hooks（4 个）	list_hooks, extract_hook, generate_hook_variations, list_hook_variations
Creative（16 个）	list_boards, get_board, create_board, save_to_board, export_board, list_ideas, get_idea_queue, create_idea, update_idea_status, create_brief, get_brief, list_briefs, export_brief, generate_script, get_script, list_scripts
Studio（2 个）	get_weekly_retro, get_benchmark
Experiments（10 个）	list_experiments, get_experiment, create_experiment, estimate_experiment, plan_experiment, update_experiment_variant, generate_experiment, retry_experiment, cancel_experiment, delete_experiment
Settings（7 个）	get_usage, get_settings, update_settings, get_refresh_logs, run_auto_analyze, get_apify_spend_status, get_digest
Gallery（1 个）	show_gallery
Fetch（1 个）	fetch_videos
Baselines（2 个）	deepen_baselines, rescore_sources
Jobs（2 个）	await_job, get_job_status
Schedule（2 个）	list_due_sources, refresh_due_sources
Workspaces（1 个）	list_workspaces

Experiments 是面向 Agent 的网站 /experiments 页面的对应功能，并封装了与 api/experiments.ts（src/experiments/service.ts）相同的服务：create_experiment（免费草稿；每个来源幻灯片仅限一个实验；或使用 mode:"brief" 创建不含来源视频的单个草稿）→ estimate_experiment 阶段 plan → 用户批准 → plan_experiment（后台分析 + 模式报告 + 变体简报）→ 状态变为 review → 可选的 update_experiment_variant → estimate_experiment 阶段 generate → 用户批准 → generate_experiment（后台渲染）。所有涉及费用的工具都会接收 approvedCredits，如果最新估算更高则会拒绝执行；未提供幂等键时会根据请求生成，因此相同的重试会重放请求，而不会重复创建。

discover 是由关键词驱动的入口：粘贴一个细分领域（关键词、#hashtags、@handles）→ AI 扩展出种子关键词 → 每个种子都会进行一次小规模的真实探测式抓取 → 从采样的字幕中提取标签和创作者，并提供观看量依据 → 从经过验证的建议中选择要跟踪的对象。网站的 Discover 页面（/discover）通过 REST 执行相同的流程（POST /api/sources/discover + /api/sources/discover/mine）。

---

费用上限行为

• 上限： 每个日历月 PROXY_TRAFFIC_CAP_GB
• 强制执行时机： 每次 refresh_source（以及单个视频下载）都会在消耗代理流量前检查
• 超出上限时： 调用会被拒绝，cap_breach 事件会写入 UsageLog，并触发可选的 APIFY_CAP_NOTIFICATION_HOOK
• 查看方式： 调用 get_scraper_spend_status（get_apify_spend_status 是同一工具的旧名称）
• 历史 Apify 费用记录仍保留在 UsageLog 中，并继续纳入报告
• 每个日历月的第一天重置。

架构说明

• 每个请求无状态： 每个 POST /mcp 都会新建一个传输层和 McpServer（WebStandardStreamableHTTPServerTransport），通过 JWT 的 sub 使用 runWithUser（AsyncLocalStorage）进行作用域隔离 → requireWorkspace()。
• 多租户： 每次查找工作区都会以 Supabase 用户 ID 为键；JWT 作用域隔离不同用户。
• 故障跟踪由数据库支持（Workspace.failureCountsJson），因此“连续失败 2 次 → 回退”规则可跨无状态请求保留。条目会在 1 小时后衰减，成功时只会清除成功后端的连续失败记录——账户级故障（OpenRouter 余额不足）也会让该后端在剩余时间内进入惩罚期。
• 没有进程内调度器： run_auto_analyze 是按需调用的工具；如需每晚批量处理，请使用 bun src/scripts/auto_analyze_cron.ts。
• 批处理折扣： run_auto_analyze 会传入 batch: true → BATCH_COST_ESTIMATES（Gemini Batch API 可享 50% 折扣）。单个 analyze_video 使用交互式费率。
• Schema 即契约： 两个分析器都会输出相同的 VideoAnalysisData Zod schema；未填充的字段为 null，并带有 analysisBasis 标签。

---

脚本

脚本	用途
bun run remote:dev	本地远程主机，启用监视模式（端口 8788）
bun run seed	填充模拟数据
bun run db:push	⚠️ 仅限本地／临时数据库，切勿用于生产环境（参见“Schema 更改”）
bun run db:generate	生成 Prisma 客户端
bun src/scripts/auto_analyze_cron.ts	用于每晚批量处理的外部 cron 入口

VPS 工作进程（可选——移除 60s 时限）

Vercel Hobby 将函数运行时间限制为 60s，完整长度的 OpenRouter 视频分析无法在此限制内完成（Qwen 分析 10s 片段需要约 45s 以上，真实片段需要超过 50s）。 同一队列也可以由长时间运行的工作进程处理，不受墙钟时间限制：

• src/worker/process-job.ts — 每项任务的处理分支（获取／分析／重新评分／刷新），由 Vercel 工作进程（api/jobs/analyze.ts）和 VPS 循环共用，因此重试／退款策略只需在一处维护。
• src/worker/index.ts — bun run worker：回收卡住的任务，按优先级领取任务（获取 → 分析 → 重新评分 → 刷新），使用 FOR UPDATE SKIP LOCKED（可与 Vercel 工作进程／pg_cron 安全并行运行，不会重复领取任务），处理时长不受限，空闲时等待 WORKER_IDLE_MS（默认 3s）。
• Docker：运行 docker build -t slashloop-worker -f worker/Dockerfile .，并使用 worker/.env.example（环境变量与 Vercel 相同，另加 OPENROUTER_VIDEO_TIMEOUT_MS／OPENROUTER_VIDEO_MAX_DURATION_SEC）。
• 如果 VPS 宕机，pg_cron 仍会持续触发 Vercel 工作进程 → 文本级分析仍可正常运行。