mcp-bajobs/README.md

MCP-Server für die Jobsuche der Bundesagentur für Arbeit (BA).

# mcp-bajobs

> **Model‑Context‑Protocol (MCP) Server** für die Jobsuche der **Bundesagentur für Arbeit**  
> Veröffentlicht auf npm - sofort startbar per `npx`.

[![npm](https://img.shields.io/npm/v/mcp-bajobs.svg?logo=npm)](https://www.npmjs.com/package/mcp-bajobs)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

---

## Warum?

Die offizielle BA-Jobbörse bietet zwar eine REST-API, doch kein Tooling für LLM-basierte
Workflows. **mcp-bajobs** stellt die Suche als *MCP-Server* bereit und liefert
normalisierte Job-Einträge, die sich hervorragend mit Chat- oder Voice-Assistenten
nutzen lassen (Claude Desktop u. a.).

---

## Schnellstart

```bash
# einmalig (ohne Installation)
npx -y mcp-bajobs@1.2.1 --about     # zeigt Version & Autor
npx -y mcp-bajobs@1.2.1             # startet den MCP‑Server (STDIO)
```

### In einem MCP‑Client (Beispiel KyBox `config.json`)

```jsonc
{
  "bajobs": {
    "keywords": ["jobs","werkstudent","arbeitsagentur","stelle"],
    "llm": "gpt-4o-mini",
    "mcp_command": "npx -y mcp-bajobs@1.2.1"
  }
}
```

---

## Verfügbare Tools

| Tool            | Zweck                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------ |
| **`about`**     | Metadaten (Name, Version, Autor)                                                                             |
| **`health_check`** | Mini‑Request gegen die BA‑API, liefert HTTP‑Status, Header & Sample‑Payload                                |
| **`get_jobs`**  | Parametrisierte Suche (JSON‑Schema siehe unten)                                                              |
| **`nl_get_jobs`** | **Natürliche Sprache → BA‑Parameter** (empfohlen für Sprachassistenten) – ruft intern `get_jobs` auf        |

### `get_jobs` – Eingabe­schema (Auszug)

| Feld              | Typ / Werte                            | Beschreibung                             |
| ----------------- | -------------------------------------- | ---------------------------------------- |
| `was`             | `string`                               | Jobtitel / Freitext                      |
| `wo`              | `string`                               | Ort                                      |
| `umkreis`         | `int (1‑500)`                          | Distanz in km                            |
| `arbeitszeit`     | `["vz","tz","ho", …]`                  | VZ=Vollzeit, TZ=Teilzeit, HO=Homeoffice …|
| `veroeffentlichtseit` | `int (Tage)`                      | Nur Anzeigen der letzten *N* Tage        |
| …                 | …                                      | …                                        |

---

## Beispiele

```text
nl_get_jobs:
"Suche Werkstudent IT in Kaiserslautern, Umkreis 40 km, letzte 30 Tage, keine Zeitarbeit, Homeoffice."
```

```text
get_jobs:
{
  "was": "Werkstudent IT",
  "wo": "Kaiserslautern",
  "umkreis": 40,
  "arbeitszeit": ["tz","ho"],
  "veroeffentlichtseit": 30,
  "zeitarbeit": false
}
```

---

## Optionale Umgebungs­variablen (`.env`)

| Variable                | Default                              | Bedeutung                          |
| ----------------------- | ------------------------------------ | ---------------------------------- |
| `AUTH_MODE`             | `apiKey` (`apiKey` / `oauth`)        | Auth‐Variante                      |
| `BA_API_KEY`            | `jobboerse-jobsuche`                 | Öffentlicher API‑Key               |
| `BA_BASE_URL`           | offizieller REST‑Pfad                | Eigener Gateway‑Pfad (optional)    |
| OAuth‑Satz …            | _leer_                               | Nur falls altes Gateway benötigt   |


---

## Lizenz

MIT © 2025 Panagiotis Natsoglou