HR-System-MCP-Server

Ein inoffizieller Prototyp eines MCP-Servers, der HR-Systemfunktionen mit Okta-Token-Validierung bereitstellt. Nur zu Evaluierungs- und Testzwecken.

📚 Dokumentation

Vollständige Dokumentation im Ordner docs/ verfügbar:

• docs/RAILWAY_README.md - Bereitstellung auf Railway.com (3 Schritte) 🚀

• docs/DOCKER_QUICK_START.md - Lokal mit Docker ausführen 🐳

• docs/README_INTEGRATION.md - Den bereitgestellten Server nutzen 🔌

• docs/CLAUDE.md - Entwicklerhandbuch & Architektur 💻

• docs/INDEX.md - Vollständiger Dokumentationsindex 📖

Related MCP server: Insperity MCP Server

Übersicht

Der HR-System-MCP-Server bietet:

• ✅ Abruf von Mitarbeiterinformationen

• ✅ Auflistung des Mitarbeiterverzeichnisses

• ✅ Zugriff auf Gehaltsinformationen

• ✅ Verwaltung von Urlaubsanträgen

• ✅ Okta OAuth 2.0 Token-Validierung für alle Tool-Aufrufe

• ✅ HTTP/NDJSON-Streaming-Unterstützung (FastMCP)

• ✅ Bereit für Railway-Deployment 🚀

Authentifizierung

Dieser Server validiert Okta-Zugriffstoken für alle Tool-Aufrufe (außer initialize):

• Token-Quelle: Okta-Autorisierungsserver

• Validierung: JWT-Signatur, Ablaufdatum, Audience-Claims

• Autorisierungs-Header: Authorization: Bearer <access_token>

Schnellstart

# Setup
cp env.example .env
# Edit .env with your Okta credentials

# Install dependencies
pip install -r requirements.txt

# Run in HTTP mode (for Okta MCP Adapter)
python main.py --http 8001

Konfiguration

.env (Umgebungsvariablen)

OKTA_DOMAIN=ijtestcustom.oktapreview.com
OKTA_AUTHORIZATION_SERVER_ID=auss2fth0mcIXHzVO1d7
OKTA_AUDIENCE=
OKTA_REQUIRED_SCOPES=
# When true (default), tools/list without auth returns 401. When false, allows unauthenticated tools/list (e.g. for gateway registration).
# PROTECTED_DISCOVERY=true

Verfügbare Tools

Nutzungsbeispiele

Direkt via VS Code/Copilot

# Endpoint
http://localhost:8001/mcp

# Authorization
Authorization: Bearer <okta_access_token>

Via Okta MCP Adapter Gateway

# Gateway will:
# 1. Receive request from client
# 2. Validate Okta token
# 3. Forward to HR System MCP
# 4. Attach authorization header

Implementierungsdetails

• Framework: FastMCP 3.0.0b1

• Server: Uvicorn (async HTTP)

• Protokoll: MCP (Model Context Protocol) mit NDJSON-Streaming

• Token-Validierung: JWKS-basierte JWT-Validierung mit Signaturprüfung

• Caching: JWKS-Schlüssel mit TTL zwischengespeichert

Anforderungsfluss

Client Request
    ↓
Authorization Header (Okta token)
    ↓
Initialize (no token needed)
    ↓
tools/list (validate token)
    ↓
tools/call (validate token)
    ↓
Response

🚀 Bereitstellungsoptionen

Vercel (Serverless) ⚡

Bereitstellung als Serverless-Funktion - automatische Skalierung, nutzungsbasierte Abrechnung

• ✅ Am besten geeignet für: Sporadische Nutzung, automatische Skalierung auf Null

• ✅ Kostenloses Kontingent: 100 GB Bandbreite/Monat

• ⚠️ Einschränkung: 10-Sekunden-Timeout (kostenlos), 5 Min. (Pro)

• 📖 Anleitung: docs/VERCEL_README.md

Railway.com (Traditioneller Server) 🚂

Bereitstellung als dauerhaft laufender Server - immer aktiv, unbegrenztes Timeout

• ✅ Am besten geeignet für: Konstanten Datenverkehr, persistente Verbindungen

• ✅ Kostenloses Kontingent: 500 Stunden/Monat (danach 5 $/Monat)

• ✅ Kein Timeout: Unbegrenzte Anfragedauer

• 📖 Anleitung: docs/RAILWAY_README.md

Docker (Lokale Entwicklung) 🐳

Lokal mit Docker ausführen - volle Kontrolle, Testen

• 📖 Anleitung: docs/DOCKER_QUICK_START.md

docker-compose up -d

Empfehlung:

• Verwenden Sie Vercel für sporadische/unvorhersehbare Nutzung (günstiger, automatische Skalierung)

• Verwenden Sie Railway für konstanten Datenverkehr oder wenn Sie lange Timeouts benötigen

Fehlerbehebung

Siehe docs/RAILWAY_DEPLOYMENT.md für eine vollständige Anleitung zur Fehlerbehebung.

Schnelle Lösungen:

• Token-Validierung schlägt fehl: Überprüfen Sie OKTA_DOMAIN und OKTA_AUTHORIZATION_SERVER_ID in .env

• Port bereits belegt: Ändern Sie den Port im Startbefehl: python main.py --http 8002

• Fehlende Umgebungsvariablen: Kopieren Sie das .env-Beispiel und füllen Sie die Werte aus

• JWKS-Abruffehler: Überprüfen Sie, ob die Okta-Domain und die Autorisierungsserver-ID korrekt sind

Projektstruktur

hr-mcp-server/
├── main.py                    # FastMCP server with HTTP handler
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Docker container definition
├── docker-compose.yml         # Docker Compose configuration
├── railway.json               # Railway deployment config
├── deploy-railway.sh          # Deployment helper script
├── test_server.sh            # Server test script
├── auth/                      # Authentication module
│   ├── __init__.py
│   └── okta_validator.py     # Okta token validation
└── docs/                      # Documentation
    ├── INDEX.md              # Documentation index
    ├── RAILWAY_README.md     # Railway quick start
    ├── RAILWAY_DEPLOYMENT.md # Complete deployment guide
    ├── DOCKER_QUICK_START.md # Docker reference
    ├── README_INTEGRATION.md # Usage guide
    ├── CLAUDE_CODE_SETUP.md  # Claude Code setup
    ├── CLAUDE.md             # Developer documentation
    └── ...more docs

Siehe docs/INDEX.md für den vollständigen Dokumentationsleitfaden.

Testen

# Using curl with Okta token
curl -X POST http://localhost:8001/mcp \
  -H "Authorization: Bearer <your_okta_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

📖 Dokumentation

Für die vollständige Dokumentation siehe den Ordner docs/:

• Erste Schritte - Dokumentationsindex

• Auf Railway bereitstellen - Cloud-Bereitstellungsanleitung

• Mit Docker ausführen - Lokale Entwicklung

• Integrationsleitfaden - Wie man den Server verwendet

• Entwicklerhandbuch - Architektur & Entwicklung

Referenzen

• MCP-Spezifikation

• FastMCP-Dokumentation

• Okta-Entwicklerdokumentation

• Railway-Dokumentation

Status

⚠️ Inoffizieller Prototyp - Nur zu Evaluierungs- und Testzwecken. Nicht für den Produktionseinsatz bestimmt.

Lizenz: Apache 2.0