Spark History Server MCP (TypeScript)

Дайте LLM доступ на чтение к вашему Spark History Server, чтобы он мог выполнять утомительную часть работы со Spark: выяснять, почему задание упало, и находить, где медленное задание тратит время.

Это порт на TypeScript проекта kubeflow/mcp-apache-spark-history-server, проверенный ответ-в-ответ против оригинального Python-кода — см. PARITY.md. Поверх порта он поставляет два агентских навыка, которые превращают сырые инструменты в экспертный рабочий процесс для анализа первопричин и настройки производительности.

                    ┌──────────────────┐
  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://…
                    └──────────────────┘

Сервер отправляет только GET-запросы к REST API History Server. Он не может ничего изменить.

Содержание

1. Быстрый старт

2. Подключение к вашему Spark History Server

3. Подключение вашего LLM-клиента

4. Установка навыков

5. Инструменты

6. Как это работает

7. Развёртывание

8. Устранение неполадок

9. Разработка

Related MCP server: Spark History MCP Server

1. Быстрый старт

Вариант A — Docker (ничего устанавливать не нужно, кроме Docker)

Запускает Spark History Server с образцами журналов событий и этим MCP:

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

В комплект входят журналы, включающие исправный конвейер и намеренно упавшее задание, так что инструментам есть что показать, прежде чем вы направите их на свой собственный кластер.

Чтобы запустить только History Server:

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

Вариант B — из исходников

Требуется Node.js 20+ (рекомендуется 22).

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

Проверка работоспособности

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

Если приложения возвращаются, вы подключены.

2. Подключение к вашему Spark History Server

Это единственное, что вам нужно настроить. Три способа, в порядке убывания приоритета — переменные окружения имеют приоритет над файлом .env, который имеет приоритет над YAML.

a. Переменные окружения (лучше всего для контейнеров и CI)

Вложенность использует двойное подчёркивание. LOCAL ниже — это просто имя, которое вы выбираете для сервера:

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

b. YAML-файл конфигурации

Сервер ищет его в следующем порядке:

1. путь, указанный в --config, или $SHS_MCP_CONFIG

2. ./config.yaml в рабочем каталоге

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"

О секретах: значения в YAML являются литеральными — ${SPARK_PASSWORD} не раскрывается. Храните учётные данные в переменных окружения (SHS_SERVERS__PROD__AUTH__PASSWORD), которые переопределяют файл. Это соответствует поведению вышестоящего проекта.

c. Файл .env

Те же имена переменных, что и в (a), читаются из .env в рабочем каталоге.

Несколько серверов

Настройте столько, сколько нужно. Инструменты принимают необязательный аргумент server; когда он опущен, сервер обнаруживает, на каком из настроенных History Server находится это приложение, и использует его (кэшируется на 5 минут). Таким образом, инженер может спросить об идентификаторе приложения, не зная, на каком кластере оно выполнялось.

Все настройки

Переменные с одним подчёркиванием (SHS_MCP_PORT) по-прежнему работают, но выводят предупреждение об устаревании, точно так же, как в вышестоящем проекте.

Доступ к History Server, к которому нет маршрута

SSH-туннель плюс use_proxy: true покрывает типичный случай закрытого кластера:

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

3. Подключение вашего LLM-клиента

stdio (Claude Code, Claude Desktop, большинство клиентов)

{
  "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"
      }
    }
  }
}

Пользователи Claude Code могут сделать то же самое одной строкой:

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 (один общий сервер для команды)

Запустите один раз, укажите всем на него:

SHS_MCP__TRANSPORT=streamable-http SHS_MCP__ADDRESS=0.0.0.0 npm start

Клиенты подключаются к http://<host>:18888/mcp. Сервер доступен только для чтения, но также не требует аутентификации — поместите его за обычный внутренний вход и включите защиту от DNS-реббиндинга, если он доступен из браузера:

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

4. Установка навыков

Инструменты дают модели доступ к данным. Навыки дают ей метод — порядок сбора доказательств, пороговые значения, отделяющие находку от шума, и правило, что она не должна называть причину, которую не видела в данных.

# 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/

Они срабатывают сами по себе от обычного вопроса — никому не нужно запоминать команду:

"ночная загрузка в 2 часа снова упала, app_1724… — не посмотришь?"

См. skills/README.md о том, что внутри каждого навыка и как расширить их знаниями вашей команды.

5. Инструменты

Все 17 находятся в src/tools/tools.ts; их JSON-схемы — в src/schemas/generated.ts. Выполните node scripts/mcp-cli.mjs list-tools, чтобы увидеть их с аргументами.

Поиск

Глубокое погружение

Диагностика

Сравнение двух запусков

Промпты

investigate_failure(app_id, server?) и compare_applications(app_a, app_b, server?, context?) — интерактивные пошаговые руководства из вышестоящего проекта, для случаев, когда инженер хочет вести сам, а не передавать анализ модели.

6. Как это работает

Вызов инструмента превращается в один или несколько GET-запросов к /api/v1/..., и JSON возвращается в том же виде, в каком его формировал оригинал на Python.

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)

Три детали, о которых стоит знать, если вы планируете модифицировать его:

• models/generated.ts и schemas/generated.ts генерируются скриптами tools/gen_models.py и tools/gen_schemas.py из вышестоящего Python-проекта. Лучше перегенерировать, чем редактировать вручную — именно это сохраняет каталог и формы ответов идентичными оригиналу.

• Используется низкоуровневый API Server, а не McpServer, потому что форма результата должна совпадать с FastMCP: один текстовый блок на элемент списка, и structuredContent только для тех инструментов, чья сигнатура на Python объявляла конкретный тип возврата.

• Обнаружение приложений позволяет инструментам опускать server. ApplicationDiscovery опрашивает каждый настроенный сервер на предмет идентификатора приложения и кэширует ответ на 5 минут.

7. Развертывание

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

Запустите его как обычный Deployment с URL в переменных окружения и учетными данными из 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 }

Процесс не имеет состояния, кроме 5-минутного кэша обнаружения, поэтому он масштабируется горизонтально без координации.

8. Устранение неполадок

Установите SHS_MCP__DEBUG=true для подробных журналов.

9. Разработка

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

Тестирование паритета между реализациями находится в parity/ — оно выполняет те же вызовы MCP к этому серверу и к оригиналу на Python и сравнивает каждый ответ. PARITY.md фиксирует результаты и точные различия, которые остаются.

Не перенесено из апстрима

Лицензия

Apache-2.0, как и в апстриме.