jobhunt

jobhunt

jobhunt is a small local bridge to the hosted Jobven MCP server, which collects job postings and employer profiles from company career sites. Through it you can search openings with a broad filter set — title and description phrases, remote type, experience level, employment type, skills, industry, language, place, salary range, sponsorship and posting dates — pick a single posting to read in full, find employers by name, open one employer's profile, or pull a sample webhook delivery to test a receiver against.

This package searches nothing itself. It answers the tool list locally, exactly as captured from the live endpoint, and forwards each tool call upstream, returning whatever comes back untouched. Per the captured descriptions, jobs returned by a search and single job or company lookups count toward the monthly allowance on your own Jobven account, while company searches are free. Nothing in this package can apply for a job, submit an application, send a message, start a checkout, or mint a key: it only reads through the five calls below, plus the sample webhook example which sends nothing and signs nothing real.

Tools

• search_jobs — search Jobven job postings with the filters of GET /v1/public/jobs. Returns 10 jobs by default (at most 25) with a plain-text excerpt of each description; get_job has the full text. Pass nextCursor back as cursor, with the same filters, for the next page. Each job returned counts toward the monthly allowance. Every argument is optional: q (title words; ANDed in any order, "double quotes" for an exact phrase, OR for either side, a leading - to exclude; case-insensitive; does not search descriptions), descriptionQuery (whole-word phrase in descriptions, matched literally; case-insensitive; slower, pair with postedAfter), remoteType (onsite, remote, hybrid, flexible), experienceLevel (entry, mid, senior, lead, executive), employmentType (full_time, part_time, contract, internship, seasonal, volunteer, temporary, per_diem, other), skills, industry, language (ISO 639-1 code), location, country (ISO 3166-1 alpha-2; XX matches jobs with no location), state, city, minSalary, maxSalary, salaryCurrency (ISO 4217 code), hasVisaSponsorship, hasRelocation, status (active, the default, or closed), postedAfter, postedBefore, listedAfter (Unix seconds), sortBy (postedAt, listedAt, title, company), order (ASC or DESC, default DESC), includeTotal, cursor, and limit (1-25, default 10).
• get_job — one Jobven job posting by id, with the full description (GET /v1/public/jobs/{id}). Required: id (a job id from search_jobs, UUID form). Optional: descriptionFormat (plain, the default, or markdown). Counts as one job toward the monthly allowance.
• search_companies — find employers Jobven collects jobs from by name (GET /v1/public/companies). Returns id, name and website; get_company has the profile. Free: company searches do not count toward the allowance. Every argument is optional: search (name contains this text), status (active or inactive; both when unset), isVerified, sortBy (name, foundedYear, totalJobsPosted, activeJobsCount, createdAt), sortOrder (ASC or DESC), page (from 1), and limit (1-25, default 10).
• get_company — one employer's profile by id (GET /v1/public/company-profiles/{id}): what it does, industry, size, founding year, headquarters and social links. Required: id (a company id from search_companies). Counts as one toward the monthly allowance.
• webhook_example — a sample Jobven webhook delivery for one event: the raw body and headers exactly as a receiver gets them, signed with an example secret, plus the signature verifier from the webhook docs in TypeScript, Python or Go. The verifier accepts the sample, so a receiver can be tested end to end. No API call, no key needed, free. Required: event (job.created, job.updated, job.closed, job.deleted) and language (typescript, python, go).

Configuration

• JOBVEN_MCP_URL (optional) — override the upstream endpoint. Defaults to https://api.jobven.com/mcp. (The override hook is this rebuild's own labelled reconstruction.)
• JOBVEN_API_KEY (optional) — when set, every upstream request carries an X-API-Key: <value> header, for the caller's own Jobven API key. When it is not set, no key header is sent. (The header name is pinned by the original's registry record, which declares a required secret X-API-Key header; the record pins no package env name, so forwarding the key from this env var is a labelled reconstruction — the original surface was captured keyless.)

Forwarding mechanics

On the first tool call the client opens a streamable HTTP session upstream: a JSON-RPC initialize request (protocolVersion 2025-03-26, clientInfo name jobhunt), then a notifications/initialized notification, then the tools/call request carrying the caller's arguments unchanged. When the upstream answers initialize with an Mcp-Session-Id header, that value rides on every later request of the session, which is reused for the life of the process. Replies may arrive as plain JSON or as server-sent events; both are read.

Successful upstream results pass through verbatim, including any isError flag the upstream sets. Failures — a JSON-RPC error, a non-2xx status, an unreadable response, or a request that cannot be completed — come back as an isError result whose text starts with jobhunt error: (this rendering is this rebuild's own labelled reconstruction).

CLI

Each tool is also a subcommand taking one JSON argument string:

npx @reneturcios/jobhunt search_jobs '{"q":"typescript","remoteType":["remote"]}'
npx @reneturcios/jobhunt get_job '{"id":"00000000-0000-0000-0000-000000000000"}'
npx @reneturcios/jobhunt search_companies '{"search":"acme"}'
npx @reneturcios/jobhunt get_company '{"id":42}'
npx @reneturcios/jobhunt webhook_example '{"event":"job.created","language":"python"}'
npx @reneturcios/jobhunt --version

Exit codes: 0 on success, 1 on an isError result, 2 on a usage error.

MCP server

npx -y @reneturcios/jobhunt mcp

MCP client config:

{
  "mcpServers": {
    "jobhunt": {
      "command": "npx",
      "args": ["-y", "@reneturcios/jobhunt", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/jobhunt
docker run --rm ghcr.io/cloudcorprecords/jobhunt --version

The container's default command is mcp, so the first form is a stdio MCP server; any other arguments reach the CLI normally.

Development

npm install
npm run build
npm test
npm run dev

The test suite runs entirely against a stubbed JSON-RPC upstream — no live network calls.

License

MIT — see LICENSE.