jobboard

jobboard

jobboard is a small keyless bridge to JobYap's hosted job search. JobYap aggregates job postings and the community discussion around them; this package exposes that search as nine MCP tools (and matching CLI subcommands) by forwarding every call to the hosted JobYap MCP endpoint. Read-only, no account, no API key.

Two of the tools do the heavy lifting. search_jobs browses the postings with structured filters (title text, companies, locations, remote/hybrid, freshness, discussion activity) and answers in under a second. match_jobs ranks postings for one specific candidate — a resume, or described experience, skills and visa needs — by reading each posting's full description, so it can take 10 to 15 seconds. Around them: get_job reads one posting in full, get_job_comments reads its discussion thread, search_locations resolves a place name to the location identifiers the filters accept, list_companies lists every tracked company with its active job count, get_job_stats reports aggregate counts, and search / fetch are the deep-research pair (natural-language search, then the full document for a result id).

Tools

• search_jobs — browse, list, count or page through postings with structured filters. Optional: query (substring matched against job titles only), companies (exact names from list_companies), locations (identifiers from search_locations), work_mode (remote or hybrid), posted_within (24h, 7d, 30d), has_comments, sort (recent default, or popular), page_size, cursor, include_total.
• match_jobs — rank the best live postings for one candidate. titles (title terms; required unless companies is given), exclude_titles, companies, exclude_companies, locations, include_anywhere (default true), work_mode, posted_within (default 7d), candidate_years, needs_sponsorship, skills (rank, never filter), limit (default 15).
• get_job — one posting in full: markdown description, salary ranges, locations with work mode, apply URL, posting dates and the canonical discussion URL. Required: id (numeric job id, a jobyap.com job URL, or a page slug).
• get_job_comments — the discussion thread for a job, chronological and threaded, with like counts. Required: id, as above. Comments are user-generated content.
• search_locations — resolve a free-text place name to location identifiers (country-XX, state-XX-YY, city-XX-YY-name). Required: query (minimum 2 characters); optional limit.
• list_companies — every company JobYap tracks, with its active job count and company-page URL.
• get_job_stats — companies tracked, active job count, newest posting date.
• search — natural-language search over postings; returns result ids, titles and citable URLs for fetch. Required: query.
• fetch — the full JobYap document for a search result id: the complete posting as markdown plus top community comments. Required: id.

The MCP layer validates each call locally before forwarding: an unknown tool name, arguments that are not a JSON object, or a missing required argument are rejected as invalid params. Well-formed arguments are forwarded exactly as given, and the upstream result comes back verbatim — content, structuredContent and any isError flag.

Configuration

• JOBYAP_MCP_URL (optional) — override the hosted endpoint. Defaults to https://mcp.jobyap.com/mcp.

Failures are reported as error results whose text starts with jobboard error: (this rebuild's own rendering): transport failures, non-2xx HTTP answers, JSON-RPC errors and unparseable responses from the upstream all take that shape, with the upstream's message or status after the prefix.

Forwarding mechanics

The bridge internals are a labelled reconstruction (the Streamable HTTP session pattern): on the first call the client POSTs an initialize request (protocolVersion 2025-03-26, empty capabilities, clientInfo name jobboard), captures the mcp-session-id response header when one is returned, POSTs notifications/initialized, then POSTs the tools/call request with the session header attached when captured. The session is reused for the life of the process. Every POST carries Content-Type: application/json and Accept: application/json, text/event-stream, and responses may be plain JSON or SSE. tools/list is served locally from the tool definitions captured from the hosted endpoint, so listing tools never touches the network.

CLI

Each tool is a subcommand taking one JSON argument string:

npx @reneturcios/jobboard search_jobs '{"query":"engineer","work_mode":"remote"}'
npx @reneturcios/jobboard match_jobs '{"titles":["software engineer"],"skills":["typescript","node"]}'
npx @reneturcios/jobboard get_job '{"id":42}'
npx @reneturcios/jobboard --version

Output is the forwarded result content as JSON. Exit codes: 0 on success, 1 on an isError result, 2 on a usage error.

MCP server

npx -y @reneturcios/jobboard mcp

MCP client config:

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

Docker

docker run -i ghcr.io/cloudcorprecords/jobboard
docker run --rm ghcr.io/cloudcorprecords/jobboard get_job '{"id":42}'

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios