让 LLM 读取你的 Spark History Server，以便它完成 Spark 工作中繁琐的部分：找出作业失败的原因，以及找出慢作业的时间花在哪里。
这是 kubeflow/mcp-apache-spark-history-server 的 TypeScript 移植版，已针对 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://…
└──────────────────┘该服务器只向 History Server 的 REST API 发出 GET 请求。它无法修改任何内容。
Related MCP server: Spark History MCP Server
启动一个加载了示例事件日志的 Spark History Server 以及 这个 MCP：
git clone https://github.com/ukonduru91/spark-history-mcp.git
cd spark-history-mcp
docker compose up --buildSpark History Server UI | |
Spark History REST API | |
MCP 端点 |
捆绑的日志包括一个健康的管道和一个故意失败的作业，因此在指向你自己的集群之前，工具会有一些真实的东西可以展示。
仅运行 History Server：
./start_local_spark_history.sh # macOS / Linux / Git Bash
.\start_local_spark_history.ps1 # Windows PowerShell需要 Node.js 20+（推荐 22）。
git clone https://github.com/ukonduru91/spark-history-mcp.git
cd spark-history-mcp
npm install
npm run build
npm startnode scripts/mcp-cli.mjs list-tools
node scripts/mcp-cli.mjs call list_applications '{"limit": 5}'如果返回了应用程序，说明你已连接。
这是你必须配置的一项。 有三种方式，优先级从高到低——环境变量优先于 .env 文件，后者优先于 YAML。
嵌套使用双下划线。下面的 LOCAL 只是你为服务器选择的一个名称：
export SHS_SERVERS__LOCAL__URL=http://spark-history.internal:18080
export SHS_SERVERS__LOCAL__DEFAULT=true服务器按以下顺序查找：
通过 --config 或 $SHS_MCP_CONFIG 指定的路径
工作目录中的 ./config.yaml
~/.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），它们会覆盖文件。这与上游项目的行为一致。
.env 文件变量名与 (a) 相同，从工作目录中的 .env 读取。
可以配置任意多个。工具接受可选的 server 参数；当省略时，服务器会发现哪个已配置的 History Server 拥有该应用程序并使用它（缓存 5 分钟）。因此，工程师可以询问一个应用程序 ID，而无需知道它运行在哪个集群上。
设置 | 环境变量 | 默认值 | 含义 |
|
|
| History Server 基础 URL |
|
|
| 未指定 |
|
| — | 基本认证 |
|
| — | 基本认证 |
|
| — | Bearer 令牌 |
|
|
| TLS 验证 |
|
| — | 私有 CA 的 PEM 捆绑包 |
|
|
| 请求超时，秒 |
|
|
| 通过 |
|
|
|
|
|
|
|
|
|
|
| HTTP 绑定地址 |
|
|
| HTTP 绑定端口 |
|
|
| 详细日志 |
单下划线变量（SHS_MCP_PORT）仍然有效，但会记录弃用警告，与上游完全一致。
SSH 隧道加上 use_proxy: true 可以覆盖常见的锁定集群场景：
ssh -D 8157 -N user@bastion # SOCKS5 proxy on :8157{
"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运行一次，让所有人都指向它：
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"]工具让模型能够访问数据。技能则赋予它方法——收集证据的顺序、区分发现与噪音的阈值，以及不得说出数据中未出现的因果的规则。
# 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/技能 | 处理对象 | 触发条件 |
| 失败、被杀死或挂起的作业 | "为什么失败了"、堆栈跟踪、应用 ID、"OOM"、"卡住" |
| 慢、昂贵或性能回退的作业 | "为什么这么慢"、"调优"、"以前需要 20 分钟"、"降低成本" |
它们会从正常问题中自行触发——没有人需要记住命令：
"凌晨 2 点的加载又失败了，app_1724…——你能看一下吗？"
参见 skills/README.md 了解每个技能的内容以及如何用你自己团队的知识扩展它们。
全部 17 个工具位于 src/tools/tools.ts；它们的 JSON 模式在
src/schemas/generated.ts 中。运行
node scripts/mcp-cli.mjs list-tools 可以查看它们及其参数。
工具 | 返回内容 |
| 应用程序，可按状态和日期过滤，或按 |
| 应用程序的作业——默认先显示失败的； |
| 阶段，相同的排序选项，可选的汇总指标 |
| 执行器，默认显示活跃的， |
| 精选的 SQL 执行摘要，可按描述过滤 |
工具 | 返回内容 |
| 单个阶段，按你的分位数显示每个任务的指标分布 |
| 每个任务的异常和堆栈跟踪——根因所在 |
| 单个查询：头部、物理计划、每个节点的指标、作业、阶段 |
| 运行时版本、Spark/系统/Hadoop 属性、类路径——按 |
| 应用程序的聚合执行器指标 |
| JVM 线程转储——仅限正在运行的应用程序 |
工具 | 返回内容 |
| 最慢的阶段和作业、溢出、GC 压力、利用率、建议 |
| 执行器添加/移除和阶段时间线摘要 |
工具 | 返回内容 |
| 配置差异——两次运行之间发生了什么变化 |
| 资源和持续时间差异 |
| 两个查询的指标差异，以及可选的计划结构差异 |
| 阶段指标和任务分位数并排显示 |
investigate_failure(app_id, server?) 和
compare_applications(app_a, app_b, server?, context?)——来自上游项目的交互式演练，适用于工程师想要自己驱动而不是将分析交给模型的情况。
一次工具调用会变成对 /api/v1/... 的一次或多次 GET 请求，返回的 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
项目生成。请重新生成而不是手动编辑——这样才能保持目录和
响应形状与原版一致。
使用底层 Server API，而不是 McpServer，因为结果
形状必须与 FastMCP 匹配：每个列表元素一个文本块，
并且只有 Python 签名声明了具体返回类型的工具才使用
structuredContent。
应用程序发现允许工具省略 server。ApplicationDiscovery
探测每个配置的服务器以查找应用程序 ID，并将答案缓存 5 分钟。
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将其作为普通 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 分钟的发现缓存外是无状态的，因此无需协调即可水平扩展。
症状 | 原因与修复 |
| URL 或端口错误，或历史服务器已关闭。从同一主机运行 |
| 该 id 不在任何已配置的服务器上，或者事件日志尚未被拾取 — |
|
|
| 这是 Spark 对某个在任何任务完成前就失败的阶段的回答。不是工具问题 — 请阅读任务异常 |
| 预期行为：历史服务器不持久化线程转储。它们仅在应用程序运行时有效 |
空的 | 检查 |
非常大的响应 | 使用 |
| EMR 持久化 UI 认证未移植；请指向可直接访问的 URL 代替 |
设置 SHS_MCP__DEBUG=true 以获取详细日志。
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/ — 它针对此服务器和 Python 原版运行相同的 MCP 调用，并对每个响应进行差异比较。PARITY.md 记录了结果和仍然存在的确切差异。
上游模块 | 状态 |
| 未移植 — 配置了 |
| 未移植 — 代理到 AWS 托管的 MCP 端点，仅在存在 AWS 凭据时注册 |
| 未移植 — 一个 Playwright 截图辅助工具，没有工具调用 |
Apache-2.0，与上游项目相同。
This server cannot be deployed
Your Databricks Lakehouse in natural language: run SQL on your SQL warehouses, track long-running qu
LLM Observability & Orchestration Agent
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
LLM Observability & Orchestration Agent (Langchain)
