joblet-mcp-grok

Standalone MCP server exposing read-only joblet.ai job search to Grok and any other standards-compliant MCP host. Independent deployment — shares no infrastructure, branch, or release train with Joblet's other connectors.

Two tools, both read-only (readOnlyHint: true):

• search_jobs — keyword search with a real upstream location filter, MCP-layer relevance filtering (title/category/industry/role token match; description-only matches rejected), expVer/near-duplicate deduplication, and a hard cap of 8 results. Ships text + structuredContent, plus an MCP Apps job-card widget for hosts that render it.

• get_job_details — full posting (description, requirements, responsibilities, salary and workplace when known, apply link) by job id.

Application URLs are passed through byte-exact (Joveo tracking preserved, no proxy or redirect). Employment type is deliberately not surfaced or filtered: the upstream search does not provide an authoritative field.

Requirements

• Node.js 18+ (developed and tested on Node 24)

• No API keys or secrets — the upstream joblet.ai API is public

Local setup

npm ci
npm run build        # bundles the widget to dist/mcp-app.html (required before start)
PORT=3010 npm start  # MCP endpoint at http://localhost:3010/mcp

Health check:

# GET /health  ->  {"status":"ok","version":"1.1.0"}

MCP endpoint: POST /mcp — Streamable HTTP, JSON responses, stateless (no session ids). Requires the spec-standard Accept: application/json, text/event-stream header. GET / returns a service banner.

Verify the MCP contract locally

MCP_URL="http://localhost:3010/mcp" node test_client.mjs
MCP_URL="http://localhost:3010/mcp" node test_widget.mjs

Or interactively: npm run inspect (MCP Inspector → Streamable HTTP → the /mcp URL).

Development

npm run typecheck    # server + widget/tests configs
npm test             # vitest suites (server pipeline, widget, a11y, logging)
npm run build        # production widget bundle

Configuration

See .env.example. Everything is optional; defaults are production-sane. MCP_REQUEST_LOG=1 enables sanitized per-call logging (hashes/lengths/counts only — never raw query text, locations, apply URLs, or credentials).

Widget notes

The job-card widget reports its intrinsic height to the host via the MCP Apps sendSizeChanged notification (height only, measured after requestAnimationFrame, change-gated to avoid resize loops) and respects a fixed host container height when one is declared. Whether a host resizes the iframe accordingly is host behavior. The View & Apply CTA uses the standards-compliant ui/open-link request with a visible, accessible in-card fallback (link + copy action) whenever the host denies or does not support it — it never fails silently.