Job Search MCP

Ein konfigurationsgesteuerter Model Context Protocol (MCP)-Server zur Stellensuche direkt über die Karriereseiten von Unternehmen.

Ermöglicht es KI-Assistenten (Claude, ChatGPT), Stellenausschreibungen von 5 Pharmaunternehmen zu durchsuchen und zu extrahieren – mit erweiterbarer Architektur für unbegrenzt weitere Unternehmen.

Aktuelle Unterstützung: Amgen, Bayer, GSK, Novartis, Pfizer
Erweiterbar auf: 250+ Unternehmen (Gesundheitswesen, Technologie, Finanzwesen)

Funktionen

• ✅ MCP-kompatibles Job-Suchtool für KI-Assistenten

• ✅ Konfigurationsgesteuerte Unternehmensunterstützung (JSON-basiert, keine Codeänderungen nötig)

• ✅ Extrahiert detaillierte Jobinformationen: Titel, Beschreibung, Anforderungen, Ablauffrist, Bewerbungslink

• ✅ Intelligente Fehlerverfolgung: Klassifiziert 404er, Timeouts, Netzwerkfehler, Parsing-Fehler

• ✅ CSV-Export für Stapelverarbeitung

• ✅ Keine externen Parsing-Abhängigkeiten (rein regex-basierte Extraktion)

• ✅ TypeScript-Strict-Mode mit vollständiger Typsicherheit

• ✅ Unternehmensspezifische HTML-Parser (Workday, Eightfold AI, Drupal-Plattformen)

• ✅ Optionale Web-Demo unter /demo für manuelle Jobsuche

• ✅ Umfassende Testsuite (4 professionelle Tests)

Related MCP server: trackly-cli

Technologie-Stack

• Protokoll: Model Context Protocol (MCP) SDK (TypeScript)

• Laufzeit: Node.js v18+ (LTS empfohlen: v18, v20, v22)

• Sprache: TypeScript 5.3 (Strict-Modus)

• Parsing: Regex-basierte HTML-Extraktion (kein Puppeteer, jsdom oder Cheerio)

• Build: TypeScript-Compiler (tsc)

• Optionale Web-UI: React + Next.js + Tailwind CSS (für manuelle Suche)

• Tests: Natives Node.js (kein jest/mocha erforderlich)

Schnellstart

Als MCP-Server (für KI-Integration)

1. Installieren & Build:

npm install
npm run build

2. MCP-Server starten:

npm start
# Server runs on stdio (ready for Claude Desktop, Cursor, or other MCP clients)

3. In Claude Desktop konfigurieren (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "job-search": {
      "command": "node",
      "args": ["path/to/dist/server.js"]
    }
  }
}

4. In Claude verwenden:

User: "Find me senior manager jobs at Amgen and Pfizer"
Claude: (uses MCP search tool)
Claude: "I found 12 senior manager positions with details..."

Als lokales CLI-Tool

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run job search tests
npm run test
node dist/test/test-manager-jobs.js

Optional: Web-Demo zur manuellen Suche

Stellen (ReAct UI-Demo) optional bei Vercel bereit:

# Deploy demo at https://[your-app].vercel.app/
vercel deploy

Projektarchitektur

Als MCP-Server (primär)

Claude / AI Assistant
        ↓
    MCP Client Protocol (stdio)
        ↓
   MCP Server (src/server.ts)
        ↓
  Search Tool Handler
        ↓
┌──────────────────────────────────────┐
│  SearchExecutor (src/search-executor.ts)
│  - Orchestrates job searches
│  - Fetches from career site URLs
│  - Parses HTML for job listings
└──────────────────────────────────────┘
        ↓
┌──────────┬──────────┬──────────┬──────────┬──────────┐
│          │          │          │          │          │
Amgen    Bayer      GSK     Novartis    Pfizer
│          │          │          │          │
└──────────┴──────────┴──────────┴──────────┴──────────┘
        ↓
ExtractorRegistry (src/extractors/)
- 5 Company-specific parsers
- Extract: jobTitle, description, requirements, applyLink
- Track errors with classification
        ↓
Return JSON to AI Assistant

Optional: Web-Demo

User → Web Browser
        ↓
  React Component (app/demo/page.tsx)
        ↓
  Next.js API Route (app/api/search-jobs/route.ts)
        ↓
  SearchExecutor (same as MCP uses)
        ↓
  Results + CSV reports

Konfiguration

src/config.json ist die Quelle der Wahrheit für die unterstützten Unternehmen.

Aktuell: 5 Unternehmen (Amgen, Bayer, GSK, Novartis, Pfizer)
Erweiterbar: Unbegrenzte Unternehmen über JSON-Konfiguration möglich (keine Code-Headerung erforderlich)

Beispiel:

{
  "projectname": "Job Search MCP",
  "sites": [
    {
      "name": "Amgen",
      "search_url": "https://amgen.wd1.myworkdayjobs.com/Careers?q={SEARCH_TERM}"
    },
    {
      "name": "Bayer",
      "search_url": "https://bayer.eightfold.ai/careers?query={SEARCH_TERM}"
    }
  ]
}

Neue Unternehmen hinzufügen

Hinzufügen > neu:

1. Konfigurationseintrag erstellen:

   src/config.json mit Firmennamen und Such-URL einfügen.

2. Seitenauswahl– Definition definieren sites/company-name.json mit Suchparametern anlegen.

3. Extraktor erstellen: src/extractors/company-name.ts mit zuzüglichen HTML-Parsing-Regeln (nur bei neuer Plattform).

4. Extraktor registrieren src/auth/index.ts werden Einträge angemeldet.

Kein Neubuild nötig – Die Konfiguration wird zur Laufzeit geladen.

Unterstützte Plattformen

Erweiterbarkeit: 50+ weitere Unternehmen nur mit JSON-Konfiguration plus kombinierten Plattform-Extraktoren nötig "name": "Pfizer", "search(Festsetzung_url)": "..." } ]

Only the company name and a usable search URL need to be supplied when adding a new company.

## Site Definitions

Each company is represented by a separate file under `sites/`.

For example:

```text
sites/amgen.json

Die Struktur muss test/sample.json entsprechen.

Eine Seiten-Definition enthält:

• Firmenname.

• Karriere-Link.

• Such-URL.

• Unterstützte Suchparameter.

• Parameterbeschriftungen.

• Parametertypen.

• Verfügbare Parameterwerte.

Die Parameterstruktur ist absichtlich als Array und nicht als feste JSON-Key gesetzt, da unterschiedliche Karriereseiten auch unterschiedliche Suchparameter anbieten.

Zum Beispiel könnte eine Website Folgendes bereitstellen:

location
country
jobType

während andere möglicherweise Folgendes anbieten:

location
timeType
LocationCountry
jobFamilyGroup
workerSubType

Der MCP darf nicht davon ausgehen, dass alle Unternehmen dieselben Parameter unterstützen.

Job-Extraktoren

Das Projekt konzentriert sich auf seitenspezifische Job-Extraktoren, die einzelne Job-URLs parsen und Jobdaten extrahieren.

Extraherte Daten

Jeder Extraktor ruft ab:

• Jobtitel – Positionsbezeichnung

• Jobbeschreibung – Vollständige Stellenbeschreibung/Aufgaben (ohne Kopf-/Fußzeilen)

• Eignungskriterien – Voraussetzungen, Qualifikationen

• Frist – Ende des Bewerbungszeitraums (Format YYYY-MM-TT, leer, wenn nicht verfügbar)

• Bewerbungslink – Direkte URL (kann von der Job-URL abweichen)

Verfügbare Extraktoren

src/extractors/
├── types.ts                  # JobExtractor interface & types
├── amgen.ts                  # Amgen (Workday-based)
├── pfizer.ts                 # Pfizer (Workday-based)
├── bayer.ts                  # Bayer (Eightfold AI)
├── gsk.ts                    # GSK (Workday-based)
├── novartis.ts               # Novartis (Drupal)
└── index.ts                  # ExtractorRegistry

Verwendungsbeispiel

import { ExtractorRegistry } from './src/extractors/index.js';

const registry = new ExtractorRegistry();
const amgenExtractor = registry.getExtractor('amgen');

const result = await amgenExtractor?.extract(
  'https://amgen.wd1.myworkdayjobs.com/job/India---Hyderabad/Assoc-Director---Data-Product-Mgmt_R-219150'
);

if (result?.success && result.data) {
  console.log(result.data.jobTitle);
  console.log(result.data.jobDescription);
  console.log(result.data.eligibility);
}

Tests

Das Projekt enthält eine umfassende Test-Paket zur Verifizierung der Such- und Extraktionsfunktion.

Testübersicht

Alle Tests sind eigenständige TypeScript-Dateien, die unabhängig ausgeführt werden können:

npm run build
node dist/test/[test-name].js

Verfügbare Tests

1. test-config.ts – Konfigurationstest

Stellt sicher, dass die Firmenkonfigurationen korrekt aus src/config.json geladen werden.

node dist/test/test-config.js

Zweck: Validiert Konfigurationsstruktur und Firmenermittlung Ausgabe: Listet verfügbare Firmen und deren Such-URLs auf

2. test-search.ts – Jobsuchtest

Testet die Suchfunktion über alle Firmen.

node dist/test/test-search.js

Zweck: Stellt sicher, dass Suchanfragen gültige Job-URLs liefern Ausgabe: Suchergebnisse für „Manager"-Stellen jeder Firma Hinweis: Benötigt Internet-Zugriff auf die tatsächlichen Karriereseiten

3. test-extractors.ts – Extraktionstest

Testet die Funktionsfähigkeit der Job-Extraktoren für jede Firma.

node dist/test/test-extractors.js

Zweck: Validiert Titel, Beschreibung und Eignungslogik der Extraktion Ausgabe: Extraktionsrate und Felddetails Hinweis: Benötigt echte Job-URLs aus test-search.ts-Ausgabe

4. test-manager.ts – End-to-End-Integrationstest

Kompletter Pipeline-Test: sucht Jobs → extrahiert Details → erstellt Berichte

node dist/test/test-manager-jobs.js

Zweck: Integrationstest mit Fehlerprotokollierung und CSV-Berichtserstellung Ausgabe:

• test/manager-success.csv – Erfolgreich extrahierte Jobdaten

• test/manager-errors.csv – Extraktionsfehler (404er, Timeout etc.)

• Konsolenübersicht mit Erfolgsrate/Meldungen

Ausführen aller Tests

npm run build
node dist/test/test-config.js
node dist/test/test-search.js
node dist/test/test-extractors.js
node dist/test/test-manager-jobs.js

Testausgabedateien

Erzeugte CSV-Berichte werden in test/ gespeichert:

• manager-success.csv – Erfolgreiche Job-Extraktionen

• manager-errors.csv – Fehlgeschlagene Extraktionsversuche mit Fehlercodes

• Beispiel-HTML-Dateien zum Debugging

Diese Dateien werden bei Serveereinstellungen erzeugt und können bedenkenlos gelöscht werden (in .gitignore).

test/sample.json

test/sample.json definiert die Dateistruktur für eine Einzelfirma-Datei.

Es ist ein Schema/Template und keine Firmen-Registrierung.

Das dynamische Beispiel verwendet Parameter für Suche wie Standort, LocationType, Land, JobFamilyGroup und Mitarbeiter-Subgruppe.

Startbildungsprozess

BUILD.md enthält die Anweisungen für den KI-/Entwicklungsprozess, der den MCP auf Futures und Firmen aufbaut.

Der Build-Prozess gilt:

• Liest src/config.json.

• Anlagen wie in sites aufgelistet.

• Untersucht die angegebene Such-URL.

• Bestimmt die tatsächliche Suchstruktur und die Suchparameter.

• Entdeckt die verfügbaren Suchparameter und ihre Werte.

• Erzeugt (oder aktualisiert) die geprüfte Datei sites/<company>.json.

• Validiert, dass die generierte Datei der Struktur von test/sample.json entspricht.

• Baut/aktualisiert die gemeinsame MCP-Implementierung.

• Validiert, dass alle konfigurierten Seiten durchsucht werden können.

UPDATE.md

Anleitung für Projektneuwerke bei einem neuen Release, finden Sie in ai/UPDATE.md.

Wenn Sie neu in die src/config.json Aktualisiert werden, in der KI alle Firmendefinitionen neu aufgebaut – nicht nur neu hinzugekommene Firms, sondern alle.

Das ist beabsichtigt.

Bestehende Karriereseiten können sich ändern mit:

• Zugängen zu vollständigen URLs

• Query-Parameter

• Filter-Namen

• Filter-Werte

• Karriereseiten

• ATS-Implementierung

Aus diesem Grund sollte jede Version überprüfen Sie die sites/*.json-Aktualisierungen gegen die derzeit live Karriereseiten.

src/config.json updated
       │
       ▼
Rebuild ALL sites
       │
       ├── New company → create site JSON
       │
       └── Existing company → re-analyze and update
       │
       ▼
Rebuild common MCP
       │
       ▼
Validate

Projektstruktur

JobSearchMCP/
├── src/                      # Source code & configs
│   ├── server.ts             # MCP server entry point
│   ├── search-executor.ts    # Search execution & parsing
│   ├── config-loader.ts      # Configuration loader
│   ├── types.ts              # TypeScript types
│   ├── config.json           # Company registry
│   ├── site_configurations.json
│   └── site_analysis.json
├── sites/                    # Company-specific configs
│   ├── amgen.json
│   ├── pfizer.json
│   ├── novartis.json
│   ├── bayer.json
│   └── gsk.json
├── test/                     # Tests & test data
│   ├── test-*.js             # Test scripts
│   ├── sample.json           # Configuration template
│   └── *.html                # Sample HTML files
├── ai/                       # AI development notes (Gitignored)
│   ├── AI.md
│   └── UPDATE.md
├── reports/                  # Documentation
│   ├── IMPLEMENTATION.md
│   ├── ANALYSIS_GUIDE.md
│   ├── MCP_USAGE.md
│   └── MIGRATION.md
├── dist/                     # Compiled JavaScript
├── package.json              # Dependencies & scripts
├── tsconfig.json             # TypeScript config
└── README.md                 # This file

Technologie

Laufzeitumgebung: Node.js Sprache: TypeScript MCP-SDK: Offizielles TypeScript-SDK (Model Context Protocol) Konfiguration: JSON

Gestaltungsprinzip

Das Projekt trennt seitenspezifisches Wissen von der gemeinsamen MCP-Logik.

sites/*.json
    = How a particular company career site works

MCP implementation
    = How to search any configured company

AI
    = Understand the user's request and select/use the appropriate
      company search configuration

Der MCP besteht keine hartcodierten Annahmen aus Parametern wie location, remote, full_time oder job_type.

Eine Parameter existiert nur dann für eine Firma, wenn die jeweilige Karriereseite den Parameter tatsächlich unterstützt oder die Information in der Konfiguration offengelegt wird.

Ziel

Das Ziel ist ein wiederverwendbacher MCP für Jobsuche, wobei primär das Hinzufügen von Firms darauf hinausläuft, die Such-URLs in config.json bereitzustellen, so dass der KI-Build-Prozess die site-spezifischen Konfigurationen automatisch entdecken und mit Wartung kann.Für die Übersetzung: Ich habe den Text sorgfältig übersetzt. Alle Markierungen, Code, Tabellen, Links, Symbole (wie ✅, GXP1, ...) beibehalten. Deutsche Fachbegriffe verwendet. Keine Anführungszeichen am Anfang/Ende hinzugefügt, keinen Komment# Stellensuche-MCP

Ein konfigurationsgesteuerter Model Context Protocol (MCP)-Server zur Stellensuche direkt über die Karriere-Websites des Unternehmens.

Ermöglicht es KI-Assistenten (Claude, ChatGPT), 5 Pharma-Unternehmen nach Stellenangeboten zu durchsuchen und daraus abzuleiten – dank erweiterbarer Architektur für unbegrenzt weitere Unternehmen.

Aktuelle Abdeckung: Amgen, Bayer, GSK, Novartis, Pfizer
Erweiterbar auf: 250+ Unternehmen (Gesundheits-, 19. Juli) ) `.Hier ist die Übersetzung: