Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Suede Crate Find artists like Radiohead and Portishead, then build me a crate"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A listening companion for people who still read the liner notes. Start with up to five artists, discover new artists and related films/books through Qloo, then follow a discovery or pass on it to refine the next crate.
Status: implementation and synthetic contract tests are available. Real Qloo integration and contest readiness require a provisioned Qloo API key and a verified live run. A configured environment variable alone does not establish a verified integration.
Requires Node.js 22 or newer. There are no runtime dependencies.
npm ci
cp .env.example .env
# Set QLOO_API_KEY in .env locally. Do not commit or share it.
npm run devOpen http://127.0.0.1:3478. Without a key the site honestly reports that discovery is unavailable. No prewritten music recommendations are substituted.
Request a hackathon key through the official developer guide. Keys are issued manually and work only against https://hackathon.api.qloo.com. This app uses the documented /search and /v2/insights GET endpoints with the X-Api-Key header.
Related MCP server: movie-rec
Resolves the exact artist using the artist-filtered search endpoint; the listener chooses the match.
Queries artist recommendations with selected entity IDs as taste signals.
Uses the same seeds for cross-domain movie and book insights.
Sends dismissed IDs as exclusions and selected discoveries as new positive seeds on the next pass.
Supports a deeper-cut setting with an artist popularity ceiling of 0.65. This is a popularity filter, not a guarantee of unfamiliarity.
Names and descriptions come from Qloo. Abstract record sleeves are original CSS and typography. Spotify, YouTube, IMDb and Google Books links are search links, not verified track, playback, playlist, or licensing integrations. Qloo associations are not claims that one artist influenced another or that music sounds similar. No LLM invents biographies, song names, scores or explanations.
POST /api/mcp is a stateless Streamable HTTP MCP endpoint supporting JSON responses, protocol negotiation, initialized notifications, ping, tool discovery and calls:
search_artists({ query }): resolve artist IDs before making a crate.
build_music_crate({ seedIds, excludedIds?, discovery? }): build or refine music/film/book discoveries. Add a liked ID to seedIds or a passed ID to excludedIds, then call again.
The browser uses GET /api/search?q=... and POST /api/crate through the same adapter and workflow. GET /api/status reports whether a key is configured, not whether a live request has passed. The workflow is an agentic tool exposed to assistant clients; it is not represented as an autonomous LLM planner.
npm test
npm run build
npx playwright install chromium
npm run test:e2e
# On a Mac with Chrome already installed:
PLAYWRIGHT_CHANNEL=chrome npm run test:e2eNode tests cover actual request contracts, ID validation, missing keys, provider failures, private caching, bounded response sizes, duplicate/exclusion filtering, cross-domain partial failure, HTTP methods, JSON bodies, MCP results and origin validation. Browser tests run full desktop and mobile flows against a synthetic test server, plus the real server's disconnected state. Fixtures are isolated under tests/ and are never imported by deployed handlers. Browser screenshots under ignored artifacts/ are synthetic test evidence, not live Qloo evidence.
The repo includes static assets and four serverless functions; vercel.json sets the public output and security headers. Use the intended team and a dedicated project. Configure QLOO_API_KEY as a sensitive server-side environment variable. Leave QLOO_BASE_URL at the hackathon default for hackathon keys. Never prefix the key with a public/client variable name. Set the project Node runtime to 22.x or 24.x.
Before submitting, verify from the public deployment: exact artist search and disambiguation, all three insight requests, follow/exclude/refine behavior, MCP initialization/discovery/real tool calls, and mobile layout. Keep the live demo working through judging. Do not submit a disconnected deployment as a functioning entry.
No accounts, payments, analytics scripts or listening-history uploads. Searches, selected IDs and exclusions are sent to Qloo via the server. UI selections are held in tab memory. Responses are cached privately in memory for five minutes, bounded to 200 cache entries per function instance. Do not publish real Qloo responses or datasets in this repo.
Input sizes, entity counts, upstream timeout and response sizes are bounded. Provider response bodies and secrets are never exposed in public errors. MCP validates browser origins; handlers have a per-instance traffic limit. This in-memory limit is not a global distributed quota. Set appropriate project firewall/provider quotas before sharing widely, and monitor Qloo allowance. Hosting and Qloo may retain operational logs under their policies. Hackathon keys expire after the event; availability then requires an appropriate replacement key.
MIT licensed. Copyright 2026 Jason Colapietro.
This server cannot be deployed
Search, analyze, and discover commercially released music using sonic intelligence.
Search multiple indices, index data, and get personalized recommendations
Personal context and preferences for AI via OAuth-approved profile sections and taste data.
The media memory layer for AI agents and their humans. Your AI client gets 29 tools to search your collection, add items, update ratings, preview music, and find patterns across everything you've read, watched, and listened to.
