ShelfBridge

Inspiration

You have found the perfect book for someone, but the shop cannot supply it. Starting again with a generic bestseller list loses the thought behind the gift. ShelfBridge uses the recipient's confirmed films, music and books to find a thoughtful alternative from a specific shelf, within a specific budget.

What it does

A buyer sets a maximum budget, optionally names an unavailable first choice, and selects exact cultural identities from Qloo search results. ShelfBridge returns up to three distinct book works. It selects the cheapest eligible edition of each work and checks stock, price, currency, unavailable titles and exclusions before asking Qloo to rank the eligible books.

The buyer can exclude an already-owned title, lower the budget or remove a taste. Changes require confirmation, and exclusions apply to every edition of the work. The buyer can compare the revised shortlist and choose a book to generate a copyable or printable gift note. An evidence panel shows the source, confirmed signals, eligible shelf boundary and decision trace.

The prototype contains 30 book works and 31 SKUs. Prices and stock are simulated; it makes no purchase or reservation. Its optional demo checkout is a browser simulation that collects no payment details and charges no money.

How we built it

Vanilla HTML, CSS and JavaScript provide the interface. A Vercel Node Function runs the policy and Qloo integration. Upstash Redis shares expiring sessions, mutation leases and atomic daily provider-call reservations across Function instances. The application does not rely on a personal computer staying online.

The published browser workflow uses real Qloo and deterministic orchestration, with no built-in LLM. Qloo's pinned official harness provides cultural identity search and book ranking restricted to the eligible shelf. The policy layer owns prices, stock, budgets and exclusions; the ranking provider cannot change them. Live provider errors are shown explicitly, without substituting fixture data.

ShelfBridge also exposes six MCP tools for an existing agent: status, taste search, shelf inspection, alternatives, confirmed refinement and gift-card selection. The bridge can call the same published Vercel HTTPS API without receiving Qloo or Redis credentials. This is the agent-tool integration; a scripted MCP protocol check does not establish an external LLM agent run. An optional OpenAI planner is experimental and is outside the published mode.

Challenges we ran into

Names are not identities. An ambiguous AURORA record was rejected after checking its external identity; Aurora Aksnes matched the intended Norwegian singer. Book search also needed to distinguish an individual novel from an omnibus.

Reliable recommendations require constraints to survive refinement and deployment. We enforce whole-work exclusions, reject stale decisions, and restore sessions through shared Redis state. Provider attempts are reserved atomically before calling Qloo, including attempts that fail. Affinity is not presented as the probability that a person will like a book.

Accomplishments

The public repository records genuine Qloo controls and the hosted HTTP journey on 9 October 2026: 13/13 controls, 10/10 nonempty taste profiles, and 8/8 hosted journey checks with five Qloo reservations and zero OpenAI calls. The hosted journey covered searches, recommendations, exclusion, a lower budget, gift-card contents, restored session and the no-stock path.

On 11 October the public homepage loaded successfully without Vercel sign-in, initialized its brief controls, and displayed "Live Qloo · no LLM · demo inventory". The source repository is public and exposes its MIT license.

What we learned

Cultural grounding and practical eligibility solve different parts of a gift recommendation. Qloo connects tastes across domains; server policy ensures the result is an option the buyer can actually choose within the brief.

What's next

Demonstrate the complete MCP workflow with an external agent, gather independent gift-buyer and bookseller feedback, and evaluate relevance against declared baselines. No measured relevance improvement, sales lift or user satisfaction result is claimed yet.

Try it

Open https://shelfbridge.vercel.app/ without an account. Use Try a gift rescue, review and explicitly select the exact Amélie (2001) and Aurora Aksnes identities, then confirm the $25 brief. Exclude an already-owned choice, confirm a rebuild, lower the budget to $15 and choose a gift. Open Why these choices? to inspect Qloo provenance and the shelf boundary. Prices and stock are simulated.

Source and setup: https://github.com/Seranov67/ShelfBridge. Agent users can connect the six MCP tools with node scripts/mcp-server.mjs --remote https://shelfbridge.vercel.app. Provider keys remain on the server; the agent supplies its own model access.

Built With

• css
• html
• javascript
• node.js
• qloo
• upstash
• vercel