RelocateRight

Inspiration

Relocation advice usually optimizes for salary, rent, or broad quality-of-life indexes. Those factors matter, but they do not answer whether a person will actually enjoy daily life in a city. A remote worker who cares about independent coffee, live jazz, and science fiction needs cultural evidence that generic LLM answers cannot reliably supply. RelocateRight treats taste affinity as one explicit decision signal. It does not pretend that cultural fit can replace authoritative checks for visas, work authorization, cost, safety, or employment eligibility.

What it does

1. Accepts one to five concrete interests and two to five candidate cities.
2. Resolves each interest through Qloo's /search endpoint.
3. Resolves each city as a destination entity.
4. Sends the resolved entity IDs to one bounded /v2/insights request.
5. Returns Qloo's ranking, available affinity evidence, resolved signals, and a transparent execution trace.
6. Exposes the workflow through both the browser and the rank_relocation_shortlist Streamable HTTP MCP tool.

How we built it

• Next.js 16 and React 19 for the web application and server-side API boundary.
• TypeScript for the bounded workflow, Qloo adapter, and validation.
• Qloo /search and /v2/insights for entity resolution and cultural ranking.
• Model Context Protocol SDK for the Streamable HTTP agent tool at /mcp.
• Zod for MCP input validation.
• Vercel for the externally accessible deployment. The Qloo key is stored only as a Vercel Production secret and is sent only from the server in the X-Api-Key header. It is never returned to the browser or committed to GitHub.

Challenges we ran into

The most important production issue appeared only after deploying the real API path. Qloo's hackathon service allows five requests per second, while the workflow needs several entity searches followed by an Insights request. A burst could make the final request fail with 429 even though every parameter was valid. The adapter now spaces outbound requests below that limit and performs at most two bounded retries using Qloo's reset headers. A regression test covers the 429 path, and the live application was reverified after deployment. The other challenge was keeping the product honest. Mock mode remains useful for local interface tests, but every mock result is visibly labelled as a fixture. The public deployment uses the real Qloo source.

Accomplishments that we're proud of

• A live, externally accessible Qloo-backed application.
• One bounded workflow shared by the web UI and MCP tool.
• Server-only secret handling with no Qloo payloads committed to the repository.
• Rate-limit-aware request pacing and bounded retry behavior.
• Nine passing automated tests, strict TypeScript checks, a passing production build, and zero production dependency vulnerabilities.
• A judge-style browser run confirmed a 200 API response, QLOO DATA source label, three ranked destinations, and no visible error.

What we learned

Qloo's entity search types and Insights filter.type values are related but not interchangeable. Reliable use requires resolving valid entity IDs first and then passing only documented signals and filters to Insights. We also learned that rate limits are part of the API contract, not an operational afterthought: the final Insights call must be scheduled alongside the searches that precede it.

What's next for RelocateRight

• Add private server-side caching for repeated comparisons without publishing Qloo response data.
• Add optional authoritative data connectors for cost and visa research while keeping those dimensions separate from taste affinity.
• Add saved comparison sessions and explicit user feedback on the ranking.
• Exercise the MCP endpoint against more agent clients and document their setup.

Built With

• github-actions
• model-context-protocol
• next.js
• qloo-api
• react
• typescript
• vercel
• zod