Inspiration

A two-person book club does not need another confident recommendation for just one person. It needs a shared starting point that respects both readers. BookBridge explores whether explicit cultural tastes can help find that bridge without inventing a match percentage or pretending to know why a person likes something. This is a new prototype, not a claim of measured reading outcomes or existing customers.

What it does

Each reader searches for and confirms one to three movies, music artists or books. BookBridge uses live Qloo entity IDs and Insights to produce a shared shelf and, when supported, a stretch choice. The interface explains the ranking method and shows how much of the candidate pool was actually ranked for each reader. Missing evidence stays unknown.

The same workflow is available as an agentic tool through the official MCP SDK 2 stdio server: search_taste_anchors discovers user-confirmable IDs, and find_shared_read returns shared-reading results. An MCP-compatible agent can call these tools; no autonomous LLM agent or paid model endpoint is bundled. The web app makes the core workflow usable directly by judges.

How we built it

This is an original Python/FastAPI application with a responsive HTML/CSS/JavaScript interface. Each reader first generates up to 20 Qloo book candidates. Their union, up to 40 IDs, is separately rescored for both readers using filter.results.entities over exactly the same pool. Shared selections minimize the worse reader rank, with deterministic ties and duplicate-title handling. Stretch is an evidenced alternative with different ranks for the two readers. Ranks are relative ordering, not calibrated probabilities of enjoyment.

Live mode depends on Qloo's /search and /v2/insights endpoints. The issued hackathon key stays server-side. A separate invented sample uses the same ranking core without network calls; it is visibly labeled and never silently replaces a live failure. The public MIT repository contains the original source, installation instructions and invented fixtures, with no API key or stored Qloo responses. AI coding assistants helped implement and review the software.

Challenges

The real API returned type contracts that differed from our initial test fixtures: search supplied a types array, while Insights used a generic type plus a specific subtype. We corrected validation against the real responses while continuing to reject wrong or malformed entity types. We also addressed member-order-dependent duplicate titles and enforced a complete streaming deadline rather than relying only on individual network-operation timeouts.

What we verified

All 37 automated tests passed on Python 3.14 and on the actual deployment host's Python 3.12 environment. A real six-request test produced a 35-book pool with 35/35 candidates ranked for each reader, three shared choices and one stretch choice. Actual official-SDK MCP discovery and live tool calls succeeded. Public Chrome checks completed the live workflow at desktop and 390-pixel mobile widths without page errors or horizontal overflow. These are technical checks using operator-selected inputs, not a user study or a comparison proving superiority to other recommenders.

What we learned and what comes next

Shared decisions need comparable evidence for both people, and honest missing-data handling matters as much as attractive recommendations. Next steps are user research with book-club pairs, evaluation of whether shared choices are useful, and production-grade quota management. The current single-process public prototype has bounded caches, timeouts and shared rate limits; it is intended for low-volume judging, not production scale.

Judge instructions

Open the public app; no login or payment is required. Select Live, search a familiar movie for Reader 1 and an artist or book for Reader 2, select one search result for each, then choose Find our bridge. Inspect shared picks, any stretch pick and coverage. The initial live-status badge must show configured access. The separate Sample mode is invented data for exploring the interface, not evidence of a live API response. The server may return a clear rate-limit or upstream error; it does not substitute sample results.

For agent use, follow the public README, install the pinned requirements, provide your own issued Qloo key as QLOO_API_KEY, and run python -m bookbridge.mcp_server. The tools are read-only; there is no public unauthenticated MCP listener or bundled paid LLM API.