refd

refd

オープンソースの AI 検索モニタリングです。ChatGPT、Perplexity、Gemini、Google AI Mode、Google AI Overviews で、AI の回答におけるブランドの可視性、言及、引用、ランキングを追跡できます。ホスト型アプリは refd.ai で利用するか、スタック全体をセルフホストできます。

Bun ワークスペースのモノレポで、独立してデプロイされる 3 つの Cloudflare Workers で構成されています。apps/api（api.refd.ai）は、Hono API、OAuth、リモート MCP、日次 cron、キューコンシューマーを担い、すべてのバインディングを保持します。apps/dashboard（dash.refd.ai）は、アセットのみを配信する Worker として動作する React SPA です。apps/web（refd.ai）は、静的な Astro 公開サイトです。ランタイムに依存しない共有コードは packages/core にあります。データの取得には BrightData（データセットスクレイパーと SERP API）を使用し、D1（Drizzle）に保存します。圧縮した生ペイロードは R2 に保存されます。

refd は、リモート MCP コネクターを通じて、同じワークスペースのインテリジェンスを AI エージェントにも提供します。デフォルトの data:read スコープは読み取り専用です。オプションの data:write スコープを有効にすると、制限付きのセットアップライフサイクルが追加され、オンボーディングレポートを 1 件開始でき、明示的な確認を経て接続を取り消せます。ホスト型ガイドは refd.ai/agents にあります。MCP コネクターガイドでは、Claude、Claude Code、ChatGPT、一般的なクライアント、ヘッドレスエージェント向けのパーソナルアクセストークン、およびセルフホストのセットアップについて説明しています。

ガイドからワンクリックで Cursor または VS Code にインストールできます。または、claude mcp add-json refd '{"type":"http","url":"https://api.refd.ai/mcp"}' を実行してください。ヘッドレスエージェントは OAuth の代わりに、Settings → Personal access tokens から取得したパーソナルアクセストークンを使用します。

仕組み

アカウントにはワークスペースが含まれ、各ワークスペースでは 1 つのブランド（競合相手、プロンプトセット、実行）が追跡されます。毎日の cron により、スケジュール監視の対象となるすべてのワークスペースに対して冪等な実行が作成され、その後キューメッセージが分配されます。データセットの各サーフェス × サンプルにつき、バッチスナップショットのトリガーが 1 つ送られます（トリガー → 通知 → 取得。バックストップのポーリングあり）。また、AI Overviews の各プロンプト × サンプルにつき、同期 SERP 呼び出しが 1 回行われます。すべての回答で、追跡対象のすべてのエンティティについてスコアが算出されます（言及の有無／引用の有無／最初に言及された位置）。生ペイロードは圧縮されて R2 にアーカイブされます。AI Overview が見つからない場合は、失敗ではなく「AIO 表示なし」という有効な結果として記録されます。実行のディスパッチでは、不変の起動プランが永続化され、制限付きバックオフで再開されます。キューの再配信があってもストレージ上の状態は収束しますが、BrightData には冪等性キーがないため、プロバイダーがリクエストを受け付けた後にクラッシュすると、有料の処理が重複する可能性があります。

開発

bun install
bun run dev    # applies local migrations, then runs all three Workers behind
               # Caddy on same-site subdomains over real HTTPS

ログイン画面で登録すると（ビジネス用メールアドレス＋8文字以上のパスワード）、最初のワークスペースが自動的に作成され、続きから再開できるセットアップウィザードが開きます。ブランド名を入力し、サイトをもとに説明文を作成してもらい、競合他社とプロンプトを選び、エンジンを選択すると、最初のレポートがリアルタイムで完成していく様子を確認できます。AI による各ステップは、いつでも手動入力に切り替えられます。標準アカウントでは、最大5つのワークスペースを作成でき、それぞれで最大25件のアクティブなプロンプトを保持し、最大3つの AI サーフェスを有効にできます。ADMIN_EMAILS に含まれるメールアドレスには、ワークスペース数とアクティブなプロンプト数の上限がなく、利用可能なすべてのサーフェスを有効にできます。

bun run dev を実行すると、Caddy（Caddyfile）が同一サイトのサブドメイン上で3つの Worker すべての前段に起動します。Astro は **https://refdlocal.io**、ダッシュボードは **https://dash.refdlocal.io**、API は https://api.refdlocal.io で利用できます（3つすべてを /etc/hosts に 127.0.0.1 として追加し、caddy trust を一度実行してください）。同一サイトのサブドメインで実際の HTTPS を使うことで、本番環境と同様に、セキュアなクロスオリジンクッキー、CORS、OAuth リダイレクト、WebSocket ストリーミングをテストできます。開発プロセスの終了時に Caddy も停止します。

ローカルのシークレットは apps/api/.dev.vars（Git 管理対象外）に設定します。対象は JWT_SECRET、BRIGHTDATA_API_TOKEN、BRIGHTDATA_WEBHOOK_SECRET（ローカルでは任意ですが、外部からアクセス可能な PUBLIC_BASE_URL が必要です）、ADMIN_EMAILS（管理者とオペレーターの許可リストをカンマ区切りで指定）、EXA_API_KEY（オンボーディングでの競合他社検索用、任意）です。シークレットではないビルド時のオリジン（VITE_API_ORIGIN、PUBLIC_DASHBOARD_ORIGIN、…）は、各アプリの .env.development / .env.production に環境ごとにコミットされています。アナリティクスには、公開サイトとダッシュボードで共用するセルフホスト型の Umami インスタンスを使用するため、アクティベーションファネルを両方にまたがって計測できます。Web アプリには PUBLIC_UMAMI_HOST_URL、PUBLIC_UMAMI_WEBSITE_ID、PUBLIC_ANALYTICS_HOSTNAME が必要で、ダッシュボードには同じ3つを VITE_* として設定する必要があります（ウェブサイト ID は同じものを使用してください）。いずれかが未設定の場合、ビルドでトラッカーは一切出力されません。セルフホスト環境ではこの設定が適しています。オンボーディングでは、シークレットではなく2つのバインディングも使用します。Workers AI（AI）と Browser Rendering（BROWSER）です。どちらも apps/api/wrangler.jsonc で remote: true に設定されているため、ローカル開発時は実際のサービスにプロキシされます。アカウントでは両方を有効にする必要があります。

• bun run check — 型チェック（全ワークスペース） · bun run lint / lint:fix — Biome · bun test — 単体テスト
• bun run build — 3つの Worker すべてをビルド · bun run deploy — ビルド、D1 のマイグレーション後、3つすべてをデプロイ（セルフホスト／手動の場合の手順です。refd.ai では、main へのマージ時に Cloudflare 経由ですべての Worker が自動的にデプロイされます）

Git worktree は wt により、追加設定なしで利用できます。wt create <name> を実行すると、リポジトリに含まれる .wt/setup.sh が依存関係をインストールし、ローカルのシークレットと Wrangler の状態をコピーするため、新しい worktree もメインのチェックアウトと同様に動作します。

セルフホスト

wrangler queues create refd-ingest && wrangler queues create refd-ingest-dlq
wrangler secret put JWT_SECRET
wrangler secret put BRIGHTDATA_API_TOKEN
wrangler secret put ADMIN_EMAILS       # comma-separated admin/operator allowlist
wrangler secret put EXA_API_KEY        # optional: onboarding competitor search
bun run db:migrate:remote
bun run deploy

bun run deploy は3つのWorkersすべてをビルドしてデプロイします（refd-api、refd-dashboard、refd-web）。それぞれのカスタムドメインを api.、dash.、およびルートドメインに割り当ててください。APIワークスペースの deploy スクリプトは、最初にリモートD1マイグレーションを実行するため、@refd/api だけをデプロイする場合（CIまたはCloudflareダッシュボードのデプロイコマンド）でも、必ずスキーマが適用されます。（ホスト環境ではCloudflareのGit連携により、これらのデプロイスクリプトがmainへのプッシュ時に実行されるため、refd.ai自体に手動のデプロイ手順はありません。）Cloudflareアカウント（Queues用のWorkers有料プランに加え、オンボーディング用にWorkers AIとBrowser Renderingを有効化）、D1データベースとR2バケット（IDと名前は apps/api/wrangler.jsonc 内）、およびBrightDataアカウントが必要です。apps/api/wrangler.jsonc の vars にデータセットIDを入力し（ダッシュボード → Web Scrapers → 各AIスクレーパー）、BRIGHTDATA_SERP_ZONE と一致するSERP APIゾーンを作成してください。セルフホスト環境では、デプロイ先のオリジン（PUBLIC_BASE_URL、DASHBOARD_ORIGIN、PUBLIC_SITE_ORIGIN、API_ORIGIN）と SCHEDULED_MONITORING_POLICY=all を設定してください。チェックイン済みの entitled ポリシーはrefd.ai用で、cronの対象をアクティブな pilot または subscribed ワークスペースに制限します。cronのスケジュール（毎日06:00 UTC）、サンプル数、地域の設定も apps/api/wrangler.jsonc にあります。

注意事項

• AIの回答は決定論的ではありません。ホスト環境のスケジュール実行では、プロンプトとサーフェスごとに SAMPLES=1 を使用します。1つのサンプルではなく、完了した実行全体を通じて傾向を読み取ってください。運用担当者は、対象を絞った手動実行で追加のサンプルをリクエストできます。
• 標準のフル実行1回あたりの上限は、アクティブなプロンプト25件 × 有効なサーフェス3件 × サンプル数です（デフォルトでは25 × 3 × 1 = 75件のレコード）。クォータは、スケジュール監視の対象となるワークスペース数に応じて増加します。
• 公開サイトは、人だけでなくエージェントにも読みやすいように構築されています。すべてのページは同じパスに .md を付けたMarkdown形式でも提供され、/llms.txt は llmstxt.org の形式に従って、それらのMarkdown版へのリンクを含みます。また、/llms-full.txt にはすべての内容がインラインで記載されています。セルフホスト環境では、これらを追加設定なしで利用できます。
• デザインシステム：DESIGN.md。スコアリング／メトリクスの仕様：docs/METRICS.md。リモートMCPとOAuth：docs/mcp.md。

コントリビューション

コントリビューションを歓迎します。セットアップ手順とPRで通過する必要のある チェックについては CONTRIBUTING.md を、コミュニティでの行動指針に ついては CODE_OF_CONDUCT.md をご覧ください。セキュリティ上の問題を見つけた場合は、 公開のissueを作成せず、SECURITY.md に従ってください。

ライセンス

MIT © refd