Common Ground

Common Ground

友人グループ全員が楽しめる夜のお出かけを計画しましょう。 どこへ行くかで意見が分かれる友人たちのために。みんなが好きなバンド、映画、番組、本をいくつか挙げます。 Qloo のクロスドメインのテイストグラフが、共通の好みをあなたの街での食事、飲み物、ライブミュージックにつなげます。 各スポットには、選ばれた理由となったお気に入りと、それぞれの友人の好みがどれだけ考慮されたかが表示されます。

ライブアプリを開く · デモ動画（85 秒） · MCP エンドポイント · ライブモードの確認

Qloo が必要な理由

• ある分野の好みから、別の分野の場所を選べます。 グループの誰もレストランやバーを挙げません。Ana は Radiohead と Dune、Tom は Kendrick Lamar と The Bear を挙げます。Qloo はその音楽、映画、テレビの好みを、街にある実際の会場につなげます。検索エンジンや LLM だけでは、そのつながりを人ごとにスコア化できません。
• Qloo は選定理由を示します。 各スポットでは Qloo の feature.explainability を使用します。アプリは選定の決め手となったお気に入り（「Radiohead、Ana、16%」）を示し、友人ごとの選定への貢献度を分けて表示します。ある友人の好みがほとんど考慮されていない場合は、そのことを伝え、もうひとつお気に入りを尋ねます。
• 友人全員について実際のスコアを表示します。 Qloo Insights は、候補となる会場ごとに各友人の親和性を算出します。各スポットには、最も満足度の低い友人の満足度が最も高くなる会場を選びます。スコアは Qloo の生の親和性スコアなので、実際の差がそのまま表示され、僅差の候補にはその旨が示されます。
• 何も捏造しません。 お気に入りはすべて Qloo の検索で照合します。見つからない名前は推測せず、そのまま報告します。ライブ呼び出しに失敗した場合は、偽のデータではなくエラーを表示します。

30 秒で試す

1. ライブアプリを開きます。「Friday in Lisbon」には 4 人の友人が登録済みです。
2. Plan our night を押します。所要時間は約 4～9 秒です。
3. 3 つのスポットを確認します。「Picked by」には各会場の選定理由となったお気に入りが表示されます。「Whose taste counts」には各友人の貢献度が表示されます。
4. Show Qloo's work を開くと、ライブ呼び出し回数と照合された Qloo エンティティを確認できます。
5. 「Birthday in New York」や「Team night in London」を試すか、自分の友人を入力します。

ナイトプランナーの下にある「Or pick one thing together」では、同じく公平な方法で映画、番組、本、アーティスト、レストランをひとつ選べます。ログインは不要です。

エージェントから使う

どちらのフローも、1 つの Streamable HTTP エンドポイント上の MCP ツール、plan_night_out と find_common_ground として利用できます。

claude mcp add --transport http common-ground https://common-ground.lipmichal.workers.dev/mcp

次のようにエージェントに依頼します。「リスボンで夜のお出かけを計画してください。Ana は Radiohead と Dune、Tom は Kendrick Lamar と The Bear、Priya は Phoebe Bridgers と Normal People が好きです。」 plan_night_out は city と、各メンバーに 1～4 個の likes を持つ 2～6 人の members を受け取ります。3 つのスポット、それぞれの選定理由となったお気に入り、友人ごとの貢献度、呼び出しトレースを返します。 find_common_ground の入力は kind、任意の tasteFrom（カテゴリ、または複数の種類のお気に入りを混在させる場合は any）、任意の location、そして各メンバーに 2～5 個の likes を持つ 2～8 人の members です。 このツールは、選ばれたもの、3 つの代替候補、各人に対する理由、Qloo の呼び出しトレースを返します。

公式 MCP レジストリでのレジストリ名は io.github.theluckystrike/common-ground です。

Qloo Agentic Hackathon向けに Michael Lip が開発しました。MIT ライセンスです。

セットアップ

Node.js 22 以降と npm を使用します。

npm ci
npm test
npm run typecheck
npm run dev

Wrangler が表示するローカル URL を開きます。 キーがない場合、アプリはローカルの合成フィクスチャで動作します（下記を参照）。

ローカルのライブモードで使うには、キーを .dev.vars に記述します。 変数名と実際の値を記載した行を使います。 このファイルは非公開にしてください。

QLOO_API_KEY=YOUR_API_KEY

Qloo が夜のプランを立てる方法

1. GET /search で、お気に入りのアーティスト、映画、テレビ番組、本をそれぞれ解決します。各お気に入りには、Qloo が返すタイプが保持されます。
2. 各立ち寄り先（夕食、ドリンク、ライブ音楽）について、1 回の GET /v2/insights 呼び出しで、全員のお気に入りを signal.interests.entities として送信します。また、都市を指定する filter.type=urn:entity:place、filter.location.query、立ち寄り先のタグ、feature.explainability=true も送信します。立ち寄り先のタグは urn:tag:genre:place:restaurant、urn:tag:category:place:bar、urn:tag:genre:place:live_music_venue です。
3. グループの呼び出しでは、都市内の候補を 30 件取得します（filter.location.radius=0）。アプリでは実在する候補を最大 20 件まで残します。候補には、Qloo の営業時間情報と、夕食ならレストランといった立ち寄り先に合うカテゴリが必要です。店舗、ショッピングモール、市場、イベント会場のレンタル施設は除外し、通りや地区も除外します。夕食では、バーやカフェでもあるレストランより、レストランのみの場所を優先します。ライブ音楽では、レストランでもある音楽施設より、音楽施設のみの場所を優先します。該当する場所が都市内に 3 件未満の場合に限り、各立ち寄り先で複合カテゴリの場所も候補にします。さらに友人ごとに 1 回 Insights を呼び出し、filter.results.entities を使って候補を採点します。
4. 各立ち寄り先では、最も低い生の親和度が最も高い場所を選びます。同点の場合はグループの平均値で決定します。同じ夜に同じ場所は 1 回だけ使用します。
5. 選ばれた場所の query.explainability スコアから、その場所につながったお気に入りがわかります。Qloo が各お気に入りをほぼ同じ重みで評価した場合、アプリはほぼ同じ割合を表示する代わりに、その場所がバランスの取れた妥協案であると伝えます。各友人の割合は、その人のお気に入りのスコアの合計です。複数人に共通するお気に入りのスコアは均等に分配されます。

友人 4 人のプランでは、検索を 8 回、Insights を 15 回呼び出します。同じプランを 30 分以内に再度リクエストした場合はキャッシュから応答するため、審査員が再生してもクォータを消費しません。

Qloo が単一の候補を選ぶ方法

Worker は環境から QLOO_API_KEY を読み取ります。 Cloudflare では、この値は Worker シークレットです。 ブラウザーにキーが渡ることはありません。

1. GET /search で query と types を使い、各お気に入りを解決します。tasteFrom が指定されている場合は、そのカテゴリ内でお気に入りを解決します。たとえば、音楽アーティストなどです。
2. GET /v2/insights を各人について個別に実行します。
3. 各 Insights リクエストでは、filter.type、signal.interests.entities、take=50 を送信します。
4. レストランのリクエストでは、filter.location.query と filter.tags=urn:tag:genre:place:restaurant も送信するため、博物館や駅は除外されます。
5. クライアントは、各エンティティの query.affinity を、ドキュメントに記載された 0 から 1 の範囲で読み取ります。
6. ツールは各人の上位候補をまとめ、ID を最大 50 件まで集めます。
7. 2 回目の Insights 呼び出しで、各人について filter.results.entities を使い、候補を採点します。
8. 各人のスコアは、その人の親和度の最高値で割ります。
9. Qloo がある人について候補のスコアを返さなかった場合、その人のスコアは 0 になります。
10. ツールは既知のお気に入りを除外し、最低スコアが最も高い候補を選びます。

キーは X-Api-Key リクエストヘッダーでのみ送信されます。 ハッカソンの呼び出し先は https://hackathon.api.qloo.com です。 呼び出しは 5 秒でタイムアウトし、説明可能性の呼び出しでは 9 秒でタイムアウトします。タイムアウトした場合は 1 回再試行します。 ハッカソンの毎秒 10 リクエストの上限を超えないよう、呼び出しの間隔を空けます。 429 の応答を受けた場合は、1 秒後に 2 回再試行します。 認証、クォータ、ネットワークのエラーは報告されます。 ライブ呼び出しが失敗しても、フィクスチャに切り替わることはありません。

検索リファレンス、 Insights リファレンス、 ハッカソン開発者ガイドをご覧ください。

キーなしでの実行

これはローカル開発専用です。ホストされたアプリではライブデータを使用します。 キーがない場合も、同じ Qloo クライアントがローカルの合成フィクスチャを読み込みます。 どちらのモードでも、同じ解決処理と公平性のコードが実行されます。 ページのバナー、結果の注記、JSON レスポンス、MCP レスポンスにモードが表示されます。 フィクスチャのアフィニティと ID は架空のものです。 Qloo のおすすめや実際のユーザーの好みを示すものではありません。 ナイトプランのテストでは、リスボンのグループに対する実際の Qloo レスポンスを1セットだけ記録し、ID、名前、タイプ、アフィニティ、説明可能性に絞って使用します。

フィクスチャファイルでは、文書化されたレスポンススキーマを参照しています。 検索では、success、duration、results 配列が返されます。 Insights では、entities と duration を含む success と results が返されます。 各 Insights エンティティには query.affinity が含まれます。

例では、映画、本、レストラン、アーティスト、テレビ番組を扱います。 キーなしで解決できるのは、フィクスチャカタログに記載された名前だけです。 不明な名前は、作り出さずに報告されます。 フィクスチャのレストランは架空のもので、ワルシャワの例に限られます。 その名前は、実在する店舗があることを示すものではありません。

デプロイ

自身の Cloudflare アカウントで Wrangler を認証します。

npm run deploy
npx wrangler secret put QLOO_API_KEY
npm run verify:live -- https://YOUR-WORKER.workers.dev

シークレットコマンドを実行すると、キーの入力が求められます。 キーをソースに保存せずに、デプロイ済みの Worker を更新します。 検証コマンドでは、モードを確認し、実際のグループ向けピックを実行します。 認証情報は出力されず、Qloo のデータも保存されません。

GET /health では、選択されているモードとキーが設定済みかどうかが報告されます。 ライブ環境のヘルスレスポンスだけで確認できるのは、設定状態のみです。 ライブ環境でピックに成功すれば、Qloo から応答があったことを確認できます。

エージェントからのアクセス

デプロイ先ホストの /mcp に、Streamable HTTP MCP クライアントを接続します。 ツールを一覧表示し、/api/pick と同じ入力で find_common_ground を呼び出します。

{
  "kind": "movie",
  "members": [
    { "name": "Ana", "likes": ["Prisoners", "Gone Girl"] },
    { "name": "Tom", "likes": ["Interstellar", "Inception"] }
  ]
}

音楽のお気に入りから映画を選ぶには、"tasteFrom": "artist" を追加します。

このツールは、構造化された結果とプレーンテキストを返します。 読み取り専用で、店舗の予約やメディアの購入は行いません。

制限事項

ナイトプランは友人2〜6人、それぞれのお気に入り1〜4件に対応しており、十分な規模の都市が必要です。 説明可能性スコアは僅差になることが多いため、「選定理由」は影響度を示すものであり、単一の原因を示すものではありません。 店舗の確認には Qloo のカテゴリタグと掲載営業時間を使用します。通り、地区、店舗、市場は除外されますが、小さな都市では、レストランでありバーでもある施設など、複合的な施設が選ばれる場合があります。

グループは、異なる名前を持つ2〜8人で構成します。 各メンバーはお気に入りを2〜5件指定します。 レストランでは、都市と、名前が指定された店舗のお気に入りが必要です。 料理のジャンル名は、レストランエンティティ ID として扱われません。 検索では、指定したタイプの最初の結果が使用されます。 曖昧な一致について、ユーザーに確認を求めることはありません。

各メンバーに対する候補は最大50件です。 結果がない場合はスコアを0として扱いますが、これはカバー範囲が限られていることを示す可能性があります。 この方式では、考えられるすべての候補をすべてのメンバーについてスコア付けするわけではありません。 2回目の Insights 処理では、メンバーごとに最大50件の候補を共有プールからスコア付けするため、最小スコアが0になることはまれです。 一致スコアは、各メンバーが返した結果のリスト内で相対的なものです。 楽しめる確率を示すものではありません。 理由は、利用可能な場合は共通タグを使い、それ以外の場合は入力された名前を使います。 因果関係についてモデルが生成した説明ではありません。

レストランの結果には、Qloo がレストランとしてタグ付けしたバーやカフェが含まれる場合があります。 1回のリクエストで、検索は最大40回、Insights 呼び出しは最大16回行われます。 公開エンドポイントには、アプリケーションのレート制限も永続キャッシュもありません。 Qloo の制限により、HTTP 429 が返されることがあります。 アプリにアカウント機能はなく、送信されたグループプロフィールも保存しません。 ライブモードでは、お気に入りの名前とエンティティ ID が Qloo に送信されます。 メンバーの名前は、アプリへのリクエスト内にとどまります。 ハッカソン後の API の利用可否は、Qloo へのアクセス状況によります。

チェック

npm test はフィクスチャのレスポンスとフェイクの fetch 関数を使用します。 Qloo には一切アクセスしません。 ナイトプランのテストでは、記録済みの Qloo レスポンスを再生します。 テストでは、ナイトプラン、説明可能性の共有、各立ち寄り先につき1会場、平等性、候補プールのスコアリング、入力エラー、認証エラー、レート制限、タイムアウト処理、フィクスチャの再生、MCP の呼び出しをカバーします。

gitleaks detect --source . --redact --no-banner
gitleaks detect --no-git --source . --redact --no-banner

スキャン設定では、ガイド内のリテラルなプレースホルダーと、ローカルで無視されるドキュメント HTML のみを許可します。 ソースコードには MIT ライセンスが適用されます。 Qloo サービスへのアクセスとデータには、引き続き Qloo の規約が適用されます。