OfferQuest MCP Server

A fast, secure, LLM-friendly Model Context Protocol (MCP) server for job and internship hunting. It searches live postings on Indeed and LinkedIn, ranks them against your resume, and tells you which keywords your resume is missing for a specific job.

Live endpoint (Streamable HTTP): https://dexter3b-offerquest-mcp.hf.space/gradio_api/mcp/

Tools

fetch_and_format_jobs

Each result includes title, company, location, job type, salary (when disclosed), posted date, direct links, a description snippet and a Job ID you can pass to ats_keywords.

rank_jobs

For every match you get: a score out of 100, matched skills, missing skills, red flags (senior title, years of experience required, no description available), links, and a Job ID. The report also lists the skills most often missing from your resume across the top results.

How the score works (pure Python, no ML dependencies):

Postings without a usable description are scored mostly on title and flagged as such.

ats_keywords

Returns keyword coverage %, missing must-haves, missing nice-to-haves, skills already covered, recurring terms in the posting that are absent from your resume, and placement tips.

Typical workflow

1. rank_jobs with your resume and target roles → get the best matches with Job IDs.

2. ats_keywords with your resume and a Job ID → see exactly what to add before applying.

3. fetch_and_format_jobs for a broader, unranked look at what's out there.

Related MCP server: LinkedIn MCP Server

Security

• Scraped text is untrusted. Postings are stripped of HTML, URLs and invisible characters, scanned for prompt-injection phrases (which are removed and flagged), and fenced inside <untrusted_posting> tags. Tool output reminds the LLM to treat it as data only.

• No SSRF. No tool fetches user-supplied URLs, and only links on linkedin.com / indeed.com are ever returned.

• Resumes stay in memory. They are never logged, cached or echoed back.

• Bounded inputs. All inputs are length-capped, and regexes are bounded to avoid ReDoS.

• Abuse controls. Per-client and global rate limits, limited concurrent searches, a scrape deadline, and a TTL cache.

• Masked errors. Internal errors and stack traces are never returned to the caller.

Limits

Installation

Requires Python 3.10+.

git clone <this-repo>
cd <this-repo>
python3 -m venv myenv
source myenv/bin/activate
pip install -r requirements.txt

Core dependencies: gradio[mcp], python-jobspy, pandas.

Usage

python3 app.py

• The Gradio UI opens at http://127.0.0.1:7860 with one tab per tool: Search, Rank, ATS Keywords.

• MCP clients connect to http://127.0.0.1:7860/gradio_api/mcp/.

Connecting an MCP client

For clients that support remote Streamable HTTP servers, use the hosted endpoint:

https://dexter3b-offerquest-mcp.hf.space/gradio_api/mcp/

For clients that only support stdio, bridge it with mcp-remote:

{
  "mcpServers": {
    "offerquest": {
      "command": "npx",
      "args": ["mcp-remote", "https://dexter3b-offerquest-mcp.hf.space/gradio_api/mcp/"]
    }
  }
}

Deployment

The server is stateless and needs no headless browser, so it runs well on Hugging Face Spaces, Docker, Render or a plain VPS.

Notes for Hugging Face Spaces (Gradio SDK):

• Start the app with demo.launch(...). Don't run your own uvicorn on port 7860, because the Space already owns it.

• Launch with ssr_mode=False. With SSR on, Gradio's Node proxy answers unknown paths with the UI, so custom routes such as /.well-known/glama.json never reach Python.

• Custom routes are registered through launch(app_kwargs={"routes": [...]}) so they are matched before Gradio's own routes.

Job sites may rate-limit or block cloud IP addresses. When that happens, the tool returns partial results with a warning instead of failing.

Disclaimer

Job data comes from third-party sites via JobSpy. Availability and accuracy depend on those sites. Scores and keyword reports are guidance, not guarantees. Only add keywords for skills you genuinely have.