Common Ground

Common Ground

Plan a night out your whole friend group will love. For friends who argue about where to go. Everyone names a few bands, films, shows or books they love. Qloo's cross-domain taste graph turns that shared taste into dinner, drinks and live music in your city. Each stop names the favourites that picked it and shows how much each friend's taste counts.

Open the live app · MCP endpoint · Live mode check

The earlier 85-second video and screenshots below show the interface before the optional date field. The video also uses older score and time labels. Use the app and the current limits below to assess present behavior.

Why it needs Qloo

• Taste in one domain picks places in another. Nobody in the group names a restaurant or a bar. Ana gives Radiohead and Dune, Tom gives Kendrick Lamar and The Bear. Qloo links that music, film and TV taste to real venues in the city. A search engine or an LLM alone has no per-person score for that link.
• Qloo says why. Each stop uses Qloo's feature.explainability. The app names the favourites that drove the pick ("Radiohead, Ana, 16%") and splits the pick between friends. When one friend's taste barely counts, the app says so and asks for one more favourite.
• A real score for every friend. Qloo Insights gives each friend an affinity for every candidate venue. Each stop is the venue whose least happy friend is happiest. Scores are raw Qloo affinity, so real gaps stay visible and close calls are labelled.
• Nothing is made up. Every favourite is matched with Qloo search. Unknown names are reported, never guessed. A failed live call shows an error, not fake data.

Try it in 30 seconds

1. Open the live app. "Night in Lisbon" is ready with four friends.
2. Optionally choose a date, then press Plan our night. A selected date filters venues by its weekday. Exact opening hours and availability are not checked. A request usually takes about 4 to 9 seconds.
3. Read the three stops. "Picked by" names the favourites behind each venue. "Whose taste counts" shows each friend's share.
4. Open Show Qloo's work for the live call count and the matched Qloo entities.
5. Try "Birthday in New York" or "Team night in London", or type your own friends.

Below the night planner, "Or pick one thing together" picks one movie, show, book, artist or restaurant the same fair way. No login is needed.

Privacy

The privacy notice is web/privacy.html in this source. Its public URL becomes available when this version is deployed.

The browser sends the city, optional date, friend names and favourites to the app's Cloudflare Worker. In live mode the Worker sends favourite text unchanged to Qloo search, then matched entity IDs to Qloo Insights, with the city and selected weekday for place and night calls. A city is required when picking a restaurant. Member names are not a separate field in those Qloo request parameters; a name typed into a favourite field is sent as favourite text. The app has no accounts and does not automatically anonymize the text you enter. The app's own web code sets no cookies and loads no analytics script. The Worker has no database binding. The web night API at /api/night can hold a plan in a per-isolate memory cache for up to 30 minutes for reuse. That period is a reuse window, not a deletion time, and entries can remain until eviction or isolate shutdown. The single-pick web API and both MCP tools do not use that cache. Result images are loaded directly from Qloo-supplied URLs, so their host receives ordinary network metadata such as IP address and user agent, and may receive the referring page depending on browser policy. Qloo and Cloudflare process data under their own policies. Their actual retention is not controlled or fully known by this app. The verified public contact is the GitHub issue tracker. Do not put personal data in a public issue.

Use it from an agent

Both flows are MCP tools on one Streamable HTTP endpoint, plan_night_out and find_common_ground.

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

Then ask your agent, for example "Plan a night out in Lisbon. Ana loves Radiohead and Dune, Tom loves Kendrick Lamar and The Bear, Priya loves Phoebe Bridgers and Normal People." plan_night_out takes a city, 2 to 6 members with 1 to 4 likes each, and an optional date in YYYY-MM-DD form. It returns the available stops, the favourites behind each, each friend's share, a call trace and dateScope. A plan can be incomplete if Qloo cannot find all three stops. find_common_ground input is kind, an optional tasteFrom (a category, or any for mixed favourites), an optional location and 2 to 8 members with 2 to 5 likes each. The tool returns the pick, three alternatives, a reason per person and a trace of the Qloo calls.

Registry name io.github.theluckystrike/common-ground in the official MCP registry.

Built for the Qloo Agentic Hackathon by Michael Lip. MIT license.

Setup

Use Node.js 22 or later and npm.

npm ci

npm test npm run typecheck npm run dev

Open the local URL printed by Wrangler. Without a key, the app runs on local synthetic fixtures (see below).

For local live mode, place the key in .dev.vars. Use a line with the variable name and your actual value. Keep this file private.

QLOO_API_KEY=YOUR_API_KEY

How Qloo plans the night

1. GET /search resolves each favourite across artists, movies, TV shows and books. Each favourite keeps the type Qloo returns.
2. For each stop (dinner, drinks, live music), one GET /v2/insights call sends everyone's favourites as signal.interests.entities, filter.type=urn:entity:place, filter.location.query with the city, a stop tag and feature.explainability=true. Stop tags are urn:tag:genre:place:restaurant, urn:tag:category:place:bar and urn:tag:genre:place:live_music_venue.
3. The group call asks for 30 venues inside the city (filter.location.radius=0). The app keeps up to 20 real venues. A venue needs opening hours in Qloo and a category that fits the stop, such as a restaurant for dinner. Shops, malls, markets and event rentals are dropped, and so are streets and districts. Dinner prefers restaurants that are not also bars or cafes, and live music prefers music venues that are not also restaurants. Each falls back to mixed venues only when a city has fewer than 3 pure ones. One more Insights call per friend scores that pool with filter.results.entities. With a selected date, every group and per-person venue call also sends Qloo's documented filter.hours weekday value.
4. Each stop is the venue with the highest lowest raw affinity. The group average breaks ties. A venue is used only once in the night.
5. The winner's query.explainability scores name the favourites behind it. When Qloo weighs the favourites about equally, the app says the venue is a balanced compromise instead of showing near-equal percentages. Each friend's share is the sum of their favourites' scores. A shared favourite is split evenly.

A four-friend plan makes 8 searches and 15 Insights calls. The same plan within 30 minutes is answered from memory, so replays by judges do not spend the quota. The cache separates each selected calendar date from other dates and from an undated request.

How Qloo drives the single pick

The Worker reads QLOO_API_KEY from its environment. On Cloudflare this value is a Worker secret. The browser never receives the key.

1. GET /search resolves each favourite with query and types. With tasteFrom, favourites resolve in that category, for example music artists.
2. GET /v2/insights runs separately for each person.
3. Each Insights request sends filter.type, signal.interests.entities and take=50.
4. Restaurant requests also send filter.location.query and filter.tags=urn:tag:genre:place:restaurant, so museums and stations drop out.
5. The client reads each entity's query.affinity in the documented zero to one range.
6. The tool pools the top candidates of every person, up to 50 IDs.
7. A second Insights call per person scores that pool with filter.results.entities.
8. Each person's scores are divided by their own highest affinity.
9. A candidate that Qloo does not score for a person gets zero for that person.
10. The tool removes known favourites and picks the highest minimum score.

The key travels only in the X-Api-Key request header. Hackathon calls use https://hackathon.api.qloo.com. Calls time out after five seconds, or nine seconds for explainability calls. A timeout is retried once. Calls are spaced to stay under the hackathon limit of 10 requests per second. A 429 answer is retried twice after one second. Authentication, quota and network errors are reported. A failed live call never switches to fixtures.

See the search reference, Insights reference and hackathon developer guide.

Running without a key

This is for local development only. The hosted app uses live data. Without a key, the same Qloo client reads local synthetic fixtures. The same resolution and fairness code runs in both modes. The page banner, result note, JSON response and MCP response show the mode. Fixture affinities and IDs are invented. They are not evidence of Qloo recommendations or real user preferences. The night plan tests use one small recorded set of real Qloo responses for a Lisbon group, trimmed to IDs, names, types, affinity and explainability.

The fixture file cites the documented response schemas. Search returns success, duration and a results array. Insights returns success and results with entities and duration. Each Insights entity has query.affinity.

The examples cover movies, books, restaurants, artists and TV shows. Only names listed in the fixture catalogue resolve without a key. Unknown names are reported rather than invented. Fixture restaurants are fictional and limited to the Warsaw example. Their names do not imply that a real venue exists.

Deploy

Authenticate Wrangler with your own Cloudflare account.

npm run deploy

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

The secret command prompts for the key. It updates the deployed Worker without storing the key in source. The verification command checks the mode and performs a real group pick. It prints no credentials and stores no Qloo data.

GET /health reports the selected mode and whether a key is configured. A live health response alone proves configuration. A successful live pick confirms that Qloo answered.

Agent access

Connect a Streamable HTTP MCP client to /mcp on the deployed host. List tools and call find_common_ground with the same input as /api/pick.

{

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

Add "tasteFrom": "artist" to pick a movie from music favourites.

The tool returns structured results and plain text. It is read only and does no