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

エージェントスキル

skills/ には、リモート MCP 用にインストール可能なエージェントスキルが含まれています。 slashloop-sources、slashloop-refresh、slashloop-gallery、 slashloop-experiments、slashloop です。npm に公開後、次のコマンドで インストールできます。

npx slashloop-skills install --codex

別のスキルルートを使う場合は、--claude、--project、または --target <skills-dir> を 指定してください。スキルディレクトリをエージェントのスキルルート（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 を実行するにはプロジェクトを再作成する必要があり、api/ のエントリーポイントが 依存する URL リライトを定義した vercel.json も削除されています。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

スキーマの変更

本番スキーマは Prisma ではなく、Supabase マイグレーションで管理します。 supabase/migrations/ の SQL ファイルは、 デフォルトブランチへのマージ時に Supabase GitHub integration によって適用されます。 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 を設定しなければ、この処理全体が何もせずに終了し、それ以外はこれまでどおり動作します。

セットアップは 1 ステップです。Vercel で SUPABASE_SECRET_KEY と CRON_SECRET を設定します。必要なバケットは 2 つです。**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は引き続き分析結果を直接返します。テキストの呼び出しを1回行うだけなので、数秒で完了します。

これは好みではなく、厳しい制限によるものです。ネイティブ分析では、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は1日1回までに制限されており、1日未満の間隔の式はデプロイ時に拒否されますが、pg_cronにはその制限がありません。毎分/api/jobs/analyzeにPOSTしますが、行の状態がqueuedまたはrunningの場合に限られるため、キューがアイドル状態なら関数呼び出しのコストはかかりません。

ジョブはほかの処理を行いません。放棄されたクレームの復旧はTypeScriptのワーカーの役割です。そのため、MAX_ATTEMPTSとSTUCK_AFTER_MINUTESの定義はsrc/lib/jobs.tsの1か所だけにあり、変更に追従しなくなる2つ目のSQL定義はありません。runningが条件に含まれているのは、クレームが放棄されたかどうかを判断できるのはワーカーだけだからです。

Supabase Vaultに次のシークレットが設定されていない場合、ジョブは意図的に何も実行しません。

Vaultのシークレット	値
cron_secret	ワーカーが確認するCRON_SECRET環境変数と一致する必要があります
worker_base_url	例：https://mcp.slashloop.dev。末尾にスラッシュを付けないでください

これらは実行時に名前で読み込まれ、マイグレーションには含まれません。VercelのCRON_SECRETをローテーションする場合は、Vault内の値も更新してください。更新しないと、ドレイン処理はエラーを通知せずに401を返します。

このためのVercel Cronへのフォールバックは、意図的に用意していません。毎分実行するジョブの重複を1日1回実行する処理として追加しても、pg_cronが停止した場合にだけ機能する3つ目のコードパスが増えるだけで、障害を表面化させず、隠してしまいます。ドレイン処理が停止すると、ジョブがqueuedに目に見えて積み上がります。これが必要なシグナルです。

後続フェーズを含む設計の全容については、docs/media-storage-plan.mdをご覧ください。

⚠️ 本番環境に対してbun run db:pushを実行しないでください。 マイグレーション履歴を完全に迂回するため、Supabaseで適用済みの状態とのずれが生じます。このコマンドは使い捨てのローカルデータベース専用です。同様に、prisma migrateも実行しないでください。Supabaseが認識していない独自の_prisma_migrationsテーブルを管理します。

ルート

ルート	目的
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。毎日実行。保存されたメディアの有効期限を切らします

3つの/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 のオリジン。チェックアウト／ポータルのリダイレクトと 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 では、これらの名前をキーにした 1 つの 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/migrations/ 内の Supabase マイグレーションによって適用されます。残る手動作業は、実際の Stripe アカウントから上記の環境変数に値を設定することです。

---

ツール一覧（63 個のツール、およびリモートホスト上の whoami）

モジュール	ツール
ソース（8）	list_sources, get_source, create_source, update_source, delete_source, refresh_source, suggest_sources, dismiss_suggested_source
検索（1）	discover
フィード（3）	get_feed, search_library, get_outlier_summary
動画（3）	get_video, analyze_video, get_video_transcript
フック（4）	list_hooks, extract_hook, generate_hook_variations, list_hook_variations
クリエイティブ（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
スタジオ（2）	get_weekly_retro, get_benchmark
実験（10）	list_experiments, get_experiment, create_experiment, estimate_experiment, plan_experiment, update_experiment_variant, generate_experiment, retry_experiment, cancel_experiment, delete_experiment
設定（7）	get_usage, get_settings, update_settings, get_refresh_logs, run_auto_analyze, get_apify_spend_status, get_digest
ギャラリー（1）	show_gallery
取得（1）	fetch_videos
ベースライン（2）	deepen_baselines, rescore_sources
ジョブ（2）	await_job, get_job_status
スケジュール（2）	list_due_sources, refresh_due_sources
ワークスペース（1）	list_workspaces

実験ツールは、サイトの /experiments ページに対応するエージェント向けの機能であり、api/experiments.ts（src/experiments/service.ts）と同じサービスを利用します。create_experiment（無料の下書き。ソース動画がある場合はソースごとに 1 件の実験、または単一の下書きでソース動画を使わない場合は mode:"brief"）→ estimate_experiment のステージ plan → ユーザーが承認 → plan_experiment（バックグラウンド分析＋パターンレポート＋バリアントのブリーフ）→ ステータス review → 必要に応じて update_experiment_variant → estimate_experiment のステージ generate → ユーザーが承認 → generate_experiment（バックグラウンドでのレンダリング）。コストが発生するすべてのツールは approvedCredits を受け取り、最新の見積もりがそれを上回る場合は実行を拒否します。冪等性キーが省略された場合はリクエストから生成されるため、同一の再試行では重複せず、以前の結果が返されます。

discover はキーワードを起点に検索する機能です。ニッチ分野（キーワード、#ハッシュタグ、@ハンドル）を入力すると、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 に保持され、引き続き報告されます
• 毎月 1 日にリセットされます。

---

アーキテクチャに関するメモ

• リクエストごとにステートレス： 各 POST /mcp は新しいトランスポートと McpServer（WebStandardStreamableHTTPServerTransport）を作成し、runWithUser（AsyncLocalStorage）を介して JWT の sub のスコープに限定し、requireWorkspace() を呼び出します。
• マルチテナント： すべてのワークスペース検索は Supabase のユーザー ID をキーにします。JWT のスコープによってユーザーを分離します。
• 失敗の追跡は DB を使用します（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 では対話型の料金を使用します。
• スキーマが契約です： どちらのアナライザーも同じ VideoAnalysisData Zod スキーマを出力します。未入力のフィールドは null となり、analysisBasis タグが付与されます。

---

スクリプト

スクリプト	目的
bun run remote:dev	ローカルのリモートホストをウォッチモードで起動（ポート 8788）
bun run seed	モックデータをシード
bun run db:push	⚠️ ローカル／使い捨て DB のみ。本番環境では絶対に使用しないでください（「スキーマの変更」を参照）
bun run db:generate	Prisma クライアントを生成
bun src/scripts/auto_analyze_cron.ts	夜間バッチ用の外部 cron エントリ

VPS ワーカー（任意 — 60 秒の上限を解消）

Vercel Hobby の関数実行時間は 60 秒が上限ですが、OpenRouter で動画を全編分析するにはこの時間を超える場合があります（10 秒のクリップでも Qwen は約 45 秒以上、実際のクリップでは 50 秒超を要します）。 同じキューを、実行時間の上限がない長時間稼働ワーカーで処理できます。

• src/worker/process-job.ts — ジョブごとの処理切り替え（fetch／ analyze／rescore／refresh）。Vercel ワーカー （api/jobs/analyze.ts）と VPS ループで共有されるため、再試行／返金ポリシーは 1 か所だけに定義されます。
• src/worker/index.ts — bun run worker：停止したジョブを再取得し、優先順位（fetch → analyze → rescore → refresh）に従って 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 のワーカーを引き続き呼び出すため、テキストレベルの分析は引き続き動作します。