Spark History Server MCP (TypeScript)

Gewähren Sie einem LLM Lesezugriff auf Ihren Spark History Server, damit es den mühsamen Teil der Spark-Arbeit übernehmen kann: herauszufinden, warum ein Job fehlgeschlagen ist, und herauszufinden, wo ein langsamer Job seine Zeit verbringt.

Es ist ein TypeScript-Port von kubeflow/mcp-apache-spark-history-server, Antwort für Antwort gegen das Python-Original verifiziert – siehe PARITY.md. Zusätzlich zum Port enthält es zwei Agent-Skills, die die rohen Tools in einen Experten-Workflow für Ursachenanalyse und Leistungsoptimierung verwandeln.

                    ┌──────────────────┐
  data engineer ──▶ │  LLM client      │   Claude Code / Claude Desktop / any MCP client
                    │  + skills        │   ← skills/ supply the method
                    └────────┬─────────┘
                             │ MCP (stdio or streamable-http)
                    ┌────────▼─────────┐
                    │  this server     │   17 tools, 2 prompts
                    └────────┬─────────┘
                             │ HTTP  GET /api/v1/...
                    ┌────────▼─────────┐
                    │ Spark History    │   your existing one, or the bundled demo
                    │ Server           │
                    └────────┬─────────┘
                             │ reads
                    ┌────────▼─────────┐
                    │ event logs       │   s3://…, hdfs://…, file://…
                    └──────────────────┘

Der Server sendet ausschließlich GET-Anfragen an die REST-API des History Servers. Er kann nichts verändern.

Inhalt

1. Schnellstart

2. Anbindung Ihres Spark History Servers

3. Verbinden Ihres LLM-Clients

4. Installieren der Skills

5. Die Tools

6. So funktioniert es

7. Bereitstellung

8. Fehlerbehebung

9. Entwicklung

Related MCP server: Spark EventLog MCP Server

1. Schnellstart

Option A — Docker (nichts zu installieren außer Docker)

Startet einen Spark History Server, der mit Beispiel-Event-Logs und diesem MCP geladen ist:

git clone https://github.com/ukonduru91/spark-history-mcp.git
cd spark-history-mcp
docker compose up --build

Die enthaltenen Logs umfassen eine fehlerfrei laufende Pipeline und einen absichtlich fehlgeschlagenen Job, sodass die Tools etwas Reales zu zeigen haben, bevor Sie sie auf Ihren eigenen Cluster ausrichten.

Um nur den History Server auszuführen:

./start_local_spark_history.sh          # macOS / Linux / Git Bash
.\start_local_spark_history.ps1         # Windows PowerShell

Option B — aus dem Quellcode

Erfordert Node.js 20+ (22 empfohlen).

git clone https://github.com/ukonduru91/spark-history-mcp.git
cd spark-history-mcp
npm install
npm run build
npm start

Prüfen, ob es funktioniert

node scripts/mcp-cli.mjs list-tools
node scripts/mcp-cli.mjs call list_applications '{"limit": 5}'

Wenn Anwendungen zurückkommen, sind Sie verbunden.

2. Anbindung Ihres Spark History Servers

Das ist die eine Sache, die Sie konfigurieren müssen. Drei Möglichkeiten, zuerst die mit höchster Priorität – Umgebungsvariablen haben Vorrang vor der .env-Datei, die wiederum Vorrang vor YAML hat.

a. Umgebungsvariablen (am besten für Container und CI)

Verschachtelung verwendet einen doppelten Unterstrich. LOCAL unten ist nur ein Name, den Sie für den Server wählen:

export SHS_SERVERS__LOCAL__URL=http://spark-history.internal:18080
export SHS_SERVERS__LOCAL__DEFAULT=true

b. Eine YAML-Konfigurationsdatei

Der Server sucht in dieser Reihenfolge danach:

1. den Pfad, der mit --config angegeben wurde, oder $SHS_MCP_CONFIG

2. ./config.yaml im Arbeitsverzeichnis

3. ~/.config/spark-mcp/config.yaml

servers:
  prod:
    url: "https://spark-history.company.com:18080"
    default: true          # used when a tool call omits `server`
    verify_ssl: true
    ssl_ca_cert: "/etc/ssl/custom-ca/ca-bundle.pem"   # private CA
    timeout: 30            # seconds
    auth:
      username: admin
      password: ${SPARK_PASSWORD}   # see the note below
      # token: <bearer token>       # or a bearer token instead

  staging:
    url: "https://spark-history-staging.company.com:18080"

Hinweis zu Geheimnissen: Werte in YAML sind wörtlich zu verstehen – ${SPARK_PASSWORD} wird nicht expandiert. Bewahren Sie Anmeldedaten in Umgebungsvariablen auf (SHS_SERVERS__PROD__AUTH__PASSWORD), die die Datei überschreiben. Dies entspricht dem Verhalten des Upstream-Projekts.

c. Eine .env-Datei

Dieselben Variablennamen wie unter (a), gelesen aus .env im Arbeitsverzeichnis.

Mehrere Server

Konfigurieren Sie so viele, wie Sie möchten. Die Tools akzeptieren ein optionales server-Argument; wenn es weggelassen wird, ermittelt der Server, welcher konfigurierte History Server diese Anwendung besitzt, und verwendet ihn (5 Minuten lang zwischengespeichert). Man kann daher nach einer Anwendungs-ID fragen, ohne zu wissen, welcher Cluster sie ausgeführt hat.

Alle Einstellungen

Variablen mit einfachem Unterstrich (SHS_MCP_PORT) funktionieren weiterhin, erzeugen aber eine Deprecation-Warnung, genau wie upstream.

Erreichen eines History Servers ohne direkte Netzwerkroute

Ein SSH-Tunnel zusammen mit use_proxy: true deckt den häufigen Fall eines abgeschotteten Clusters ab:

ssh -D 8157 -N user@bastion    # SOCKS5 proxy on :8157

3. Verbinden Ihres LLM-Clients

stdio (Claude Code, Claude Desktop, die meisten Clients)

{
  "mcpServers": {
    "spark-history": {
      "command": "node",
      "args": ["/absolute/path/to/spark-history-mcp/dist/index.js"],
      "env": {
        "SHS_MCP__TRANSPORT": "stdio",
        "SHS_SERVERS__PROD__URL": "https://spark-history.company.com:18080",
        "SHS_SERVERS__PROD__DEFAULT": "true"
      }
    }
  }
}

Nutzer von Claude Code können dasselbe in einer Zeile tun:

claude mcp add spark-history \
  --env SHS_MCP__TRANSPORT=stdio \
  --env SHS_SERVERS__PROD__URL=https://spark-history.company.com:18080 \
  --env SHS_SERVERS__PROD__DEFAULT=true \
  -- node /absolute/path/to/spark-history-mcp/dist/index.js

streamable-http (ein gemeinsamer Server für ein Team)

Führen Sie ihn einmal aus und verweisen Sie alle darauf:

SHS_MCP__TRANSPORT=streamable-http SHS_MCP__ADDRESS=0.0.0.0 npm start

Clients verbinden sich mit http://<host>:18888/mcp. Der Server ist schreibgeschützt, aber auch unauthentifiziert – setzen Sie ihn hinter Ihren üblichen internen Ingress und aktivieren Sie den DNS-Rebinding-Schutz, wenn er aus einem Browser erreichbar ist:

mcp:
  transport_security:
    enable_dns_rebinding_protection: true
    allowed_hosts: ["spark-mcp.internal:*"]
    allowed_origins: ["https://spark-mcp.internal"]

4. Installieren der Skills

Die Tools geben dem Modell Zugriff auf die Daten. Die Skills geben ihm die Methode – die Reihenfolge, in der es Beweise sammelt, die Schwellenwerte, die einen Befund von Rauschen trennen, und die Regel, dass es keine Ursache nennen darf, die es nicht in den Daten gesehen hat.

# per project
mkdir -p .claude/skills
cp -r skills/spark-rca skills/spark-optimization .claude/skills/

# or for every project
mkdir -p ~/.claude/skills
cp -r skills/spark-rca skills/spark-optimization ~/.claude/skills/

Sie werden von selbst durch eine normale Frage ausgelöst – niemand muss sich einen Befehl merken:

"die 2-Uhr-Ladung ist schon wieder fehlgeschlagen, app_1724… – kannst du mal schauen?"

In skills/README.md erfahren Sie, was in jedem Skill steckt und wie Sie sie mit dem Wissen Ihres Teams erweitern können.

5. Die Tools

Alle 17 Tools befinden sich in src/tools/tools.ts; ihre JSON-Schemas liegen in src/schemas/generated.ts. Führen Sie node scripts/mcp-cli.mjs list-tools aus, um sie mit ihren Argumenten zu sehen.

Dinge finden

Ins Detail gehen

Diagnose

Zwei Läufe vergleichen

Prompts

investigate_failure(app_id, server?) und compare_applications(app_a, app_b, server?, context?) – interaktive Schritt-für-Schritt-Anleitungen aus dem Upstream-Projekt, für den Fall, dass der Entwickler die Steuerung übernehmen möchte, statt die Analyse abzugeben.

6. So funktioniert es

Ein Tool-Aufruf wird zu einer oder mehreren GET-Anfragen an /api/v1/..., und das JSON kommt exakt in der Form zurück, in der es das Python-Original erzeugt hat.

src/
  index.ts                 CLI entry, transport selection (stdio | streamable-http)
  config/config.ts         YAML + .env + SHS_* resolution and precedence
  core/
    app.ts                 MCP request handlers; maps results to content blocks
    validation.ts          pydantic-compatible argument validation and messages
    json.ts                Python-compatible JSON rendering
    pyfloat.ts             int/float fidelity across the JSON round-trip
    pyrepr.ts              Python repr() for validation messages
    errors.ts              error text shaping
  api/
    httpClient.ts          HTTP transport, ApiException taxonomy, auth, TLS, SOCKS
    sparkClient.ts         Spark REST facade: pagination, attempts, status filters
  models/
    generated.ts           model shapes, generated from the upstream OpenAPI models
    deserialize.ts         from_dict / model_dump equivalents
    mcpTypes.ts            curated LLM-facing output models
  tools/tools.ts           the 17 tools
  prompts/prompts.ts       the 2 prompts
  schemas/generated.ts     tool + prompt catalogue (names, descriptions, schemas)

Drei Details, die Sie kennen sollten, wenn Sie es ändern möchten:

• models/generated.ts und schemas/generated.ts werden generiert – von tools/gen_models.py und tools/gen_schemas.py – aus dem Upstream-Python-Projekt. Generieren Sie neu, statt von Hand zu editieren – genau das hält den Katalog und die Antwortstrukturen identisch zum Original.

• Es wird die Low-Level-Server-API verwendet, nicht McpServer, weil die Ergebnisstruktur der von FastMCP entsprechen muss: ein Textblock pro Listenelement und structuredContent nur für die Tools, deren Python-Signatur einen konkreten Rückgabetyp deklariert hat.

• Anwendungsermittlung (Application Discovery) ermöglicht es den Tools, server wegzulassen. ApplicationDiscovery prüft jeden konfigurierten Server auf die Anwendungs-ID und speichert die Antwort 5 Minuten lang zwischen.

7. Bereitstellung

Docker

docker build -t spark-history-mcp .
docker run -p 18888:18888 \
  -e SHS_SERVERS__PROD__URL=https://spark-history.company.com:18080 \
  -e SHS_SERVERS__PROD__DEFAULT=true \
  -e SHS_MCP__ADDRESS=0.0.0.0 \
  spark-history-mcp

Kubernetes

Betreiben Sie es als normales Deployment mit der URL als Umgebungsvariable und Anmeldedaten aus einem Secret:

env:
  - name: SHS_MCP__TRANSPORT
    value: streamable-http
  - name: SHS_MCP__ADDRESS
    value: "0.0.0.0"
  - name: SHS_SERVERS__PROD__URL
    value: http://spark-history-server.spark.svc.cluster.local:18080
  - name: SHS_SERVERS__PROD__DEFAULT
    value: "true"
  - name: SHS_SERVERS__PROD__AUTH__TOKEN
    valueFrom:
      secretKeyRef: { name: spark-history-auth, key: token }

Bis auf den 5-minütigen Discovery-Cache ist der Prozess zustandslos, sodass er ohne Koordination horizontal skaliert.

8. Fehlerbehebung

Für ausführliche Logs setzen Sie SHS_MCP__DEBUG=true.

9. Entwicklung

npm install
npm run build        # compile to dist/
npm run dev          # run from source, no build step
npm test             # unit tests
npm run typecheck    # tsc --noEmit

Die Paritätstests über Implementierungen hinweg befinden sich in parity/ — sie führen dieselben MCP-Aufrufe gegen diesen Server und das Python-Original aus und erstellen für jede Antwort einen Diff. PARITY.md dokumentiert die Ergebnisse und die genauen verbleibenden Unterschiede.

Nicht aus dem Upstream portiert

Lizenz

Apache-2.0, wie auch beim Upstream-Projekt.