TasteBridge

An agent and MCP server that finds what two people will both enjoy: fair, explainable picks built only from Qloo Taste AI data.

Comment

Inspiration

Most recommenders serve one person, but real choices are shared: a couple picking a film, friends choosing a book-club title, travel buddies looking for a bar in a new city. Splitting the difference by hand usually ends with whatever one person already likes. And when you ask an AI assistant "what would we both like?", it tends to guess, or to invent titles.

What it does

TasteBridge finds common ground between two people's tastes. You give it each person's favorites (movies, books, artists, shows, games, places) and a target category. A deterministic agent then:

  1. resolves every favorite to a Qloo entity with GET /search,
  2. compares the two taste profiles with GET /v2/insights/compare (shared taste tags and what is distinctive to each person),
  3. asks GET /v2/insights for candidates scored against both people's favorites, with explainability on,
  4. re-ranks for fairness: each person's share of the signal comes from Qloo's explainability, and balance = 1 - (max share - min share), so a pick that only one person would love does not win on raw affinity,
  5. explains every pick with Qloo data only: affinity, how much each person's favorites drive it (and their strongest favorite), and the taste tags both people share.

It ships three ways: a web demo, a CLI and an MCP server (Streamable HTTP, 5 read-only tools) that any AI agent can call. There is no LLM in the loop and nothing is invented: every title, score and tag comes from a Qloo API response.

How we built it

  • Node.js 22, a zero-build web demo (desktop and phone) and a CLI.
  • The official MCP TypeScript SDK (spec 2025-11-25, Streamable HTTP) with Zod schemas for 5 tools: qloo_resolve_entities, qloo_recommend, qloo_compare_tastes, qloo_explain_match, tastebridge_common_ground.
  • A GET-only Qloo client with timeouts, a 10-minute in-memory cache and clear error codes. The API key stays server-side.
  • A deterministic agent loop: plan, resolve, compare, recommend, rank, explain. Every run returns its plan and a trace of each Qloo call (endpoint, HTTP status, latency).
  • Hardening for a public server: Content-Security-Policy, Host/Origin validation and a 30 requests per minute per-IP rate limit.
  • 25 automated tests (offline tests use clearly fictional fixtures; one live smoke test calls Qloo).
  • Hosted on Render's free tier: https://tastebridge-qloo.onrender.com/

Challenges we ran into

  • Our first prototype sent POST + JSON to /v2/insights. The docs require GET with query parameters and entity IDs from /search, so we rewrote the client.
  • The documented type urn:entity:video_game returns HTTP 400 on the hackathon API, while urn:entity:videogame works. We verified this live and documented it in the README.
  • Qloo returns the same tag name under different IDs (for example "Drama"), so tags are de-duplicated by name, with a regression test.
  • The MCP SDK answers 2025-11-25 requests with an SSE stream, so the tests and examples handle both JSON and SSE responses.

Accomplishments that we're proud of

  • Fair, fully explainable ranking built from Qloo's own explainability data, not from a language model's opinion.
  • A live MCP endpoint that any agent can use today: https://tastebridge-qloo.onrender.com/mcp
  • Live smoke test: 6 of 6 Qloo calls returned HTTP 200. All 25 automated tests pass.

What we learned

Explainability is what turns a recommender into a trustworthy agent tool. When every pick carries how much each person's favorites drive it, an agent can justify a shared choice instead of guessing.

What's next

  • Groups of more than two people.
  • "Why not" explanations for candidates that were filtered out.
  • Publishing the MCP server in public MCP registries, so agents can discover it.

Note: the free hosting tier sleeps when idle, so the first request after a quiet period can take up to a minute.

Built With

Share this project:

Updates

Submission history