job-search

▶ Try it now: https://job-search-mcp-tau.vercel.app No sign-up, no keys. Fill a profile, search jobs, generate a cover letter, rehearse a Q&A.

Where it finds jobs

Tick "Include live listings" and it fetches from five keyless sources in parallel, filtered by your profile's role and location, then merges, de-duplicates, ranks, and verifies every link is reachable before showing it.

Without live listings, search runs instantly over a bundled, illustrative sample dataset.

Related MCP server: job-search-mcp

Your profile

Everything is keyed off a simple candidate profile. It's saved only in your browser (localStorage) and passed inline to each call — the server stays stateless.

The four capabilities — demo vs. live

The live deployment runs in Live AI mode via Groq (llama-3.3-70b-versatile), so letters and answers are model-generated. The banner in the UI shows Demo vs Live AI at a glance.

Use it as an MCP server

This app is a remote MCP server — connect any MCP client (Claude Desktop, Claude Code, Cursor, …) and let the model fetch jobs for a candidate.

• Endpoint: https://job-search-mcp-tau.vercel.app/api/mcp (Streamable HTTP + SSE)

• Tools: profile_upsert, jobs_search, letter_generate, qa_reply

{
  "mcpServers": {
    "job-search": { "url": "https://job-search-mcp-tau.vercel.app/api/mcp" }
  }
}

"Find remote data-engineering roles for someone strong in Python, Spark and SQL" → the model calls jobs_search and returns ranked, link-checked jobs with fit scores.

REST API

curl -s -X POST https://job-search-mcp-tau.vercel.app/api/jobs \
  -H "Content-Type: application/json" \
  -d '{"query":"python data engineer","profile":{"skills":["python","spark","sql"]},"live":true,"limit":5}'

Run locally

npm install
npm run dev      # http://localhost:3000
npm test         # 68 unit tests (pure functions, no network)

No .env needed — it starts in demo mode. To enable live AI, copy .env.example to .env.local and set one key (GROQ_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, or HF_TOKEN).

Deploy to Vercel

npm i -g vercel
vercel --prod    # prompts for login the first time

Vercel auto-detects Next.js. Add an API key under Project → Settings → Environment Variables to enable live AI, then redeploy.

How it's built

app/
  page.tsx                       Web UI: 4 tabs (Profile, Job Search, Cover Letter, Q&A)
  api/{config,profile,jobs,letter,qa}/route.ts   thin REST adapters
  api/[transport]/route.ts       MCP endpoint (4 tools) at /api/mcp
lib/
  tools/{profile,search,letter,qa}.ts   pure capability functions (+ unit tests)
  ranking.ts                     TF-IDF cosine over job text (pure TS)
  jobs-source.ts                 5 live sources + bundled sample, mappers, dedupe
  link-check.ts                  reachability validation for live job links
  config.ts                      env → real-vs-demo decision (the only env reader)
  llm.ts                         provider abstraction (Groq / OpenAI / Anthropic / HF ↔ demo)
  service.ts                     composition root shared by REST + MCP

The capability functions in lib/tools/* and lib/ranking.ts are pure — no Next, no env, no network — and unit-tested in isolation. lib/config.ts is the only place that reads env and decides demo-vs-live; tools receive an injected llm and never branch on environment. REST and MCP both call lib/service.ts, so the two faces can never drift.

Notes

• Attribution: live job data comes from Remotive, The Muse, Arbeitnow, RemoteOK and Jobicy. RemoteOK and The Muse ask that you credit them when displaying results.

• Stateless by design — no database; your profile lives in the browser.

• A clean Vercel rebuild of the original Hugging Face Spaces "Job Search MCP" concept (no torch / faiss / Gradio).

License

MIT © VikramKavuri