joblet-mcp-grok

Eigenständiger MCP-Server, der die schreibgeschützte joblet.ai-Jobsuche für Grok und jeden anderen standardkonformen MCP-Host bereitstellt. Unabhängige Bereitstellung – teilt keine Infrastruktur, keinen Branch und keinen Release-Zug mit den anderen Connectoren von Joblet.

Zwei Tools, beide schreibgeschützt (readOnlyHint: true):

• search_jobs – Stichwortsuche mit echtem Upstream-Standortfilter, Relevanzfilterung auf MCP-Ebene (Token-Abgleich von Titel/Kategorie/Branche/Rolle; Nur-Beschreibungs-Treffer werden abgelehnt), Deduplizierung von expVer/ Fast-Duplikaten und einer harten Obergrenze von 8 Ergebnissen. Liefert Text + structuredContent sowie ein MCP-Apps-Jobkarten-Widget für Hosts, die es rendern.

• get_job_details – Vollständige Stellenausschreibung (Beschreibung, Anforderungen, Verantwortlichkeiten, Gehalt und Arbeitsplatz, sofern bekannt, Bewerbungslink) anhand der Job-ID.

Anwendungs-URLs werden bytegenau durchgereicht (Joveo-Tracking bleibt erhalten, kein Proxy oder Redirect). Der Beschäftigungstyp wird bewusst nicht angezeigt oder gefiltert: Die Upstream-Suche bietet kein maßgebliches Feld.

Voraussetzungen

• Node.js 18+ (entwickelt und getestet auf Node 24)

• Keine API-Schlüssel oder Geheimnisse – die Upstream-API von joblet.ai ist öffentlich

Lokale Einrichtung

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-Endpunkt: POST /mcp – Streamable HTTP, JSON-Antworten, zustandslos (keine Session-IDs). Erfordert den spezifikationskonformen Accept: application/json, text/event-stream-Header. GET / gibt einen Service-Banner zurück.

MCP-Vertrag lokal verifizieren

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

Oder interaktiv: npm run inspect (MCP Inspector → Streamable HTTP → die /mcp-URL).

Entwicklung

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

Konfiguration

Siehe .env.example. Alles ist optional; die Standardwerte sind produktionsgerecht. MCP_REQUEST_LOG=1 aktiviert bereinigte Pro-Aufruf-Protokollierung (nur Hashes/Längen/Zählungen – niemals roher Suchtext, Standorte, Bewerbungs-URLs oder Anmeldedaten).

Widget-Hinweise

Das Jobkarten-Widget meldet dem Host seine intrinsische Höhe über die MCP-Apps-sendSizeChanged-Benachrichtigung (nur Höhe, gemessen nach requestAnimationFrame, änderungsgesteuert, um Größenänderungsschleifen zu vermeiden) und respektiert eine feste Host-Containerhöhe, sofern eine deklariert ist. Ob ein Host den iframe entsprechend skaliert, ist Host-Verhalten. Der „View & Apply“-CTA verwendet die standardkonforme ui/open-link-Anfrage mit einem sichtbaren, barrierefreien Fallback in der Karte (Link + Kopieraktion), falls der Host sie ablehnt oder nicht unterstützt – er schlägt nie still fehl.