Kubeflow Spark AI 툴킷
CI
Python 3.12+
MCP
License
Kubeflow
Slack
AI 에이전트와 엔지니어를 Apache Spark History Server에 연결하여 지능적인 작업 분석, 성능 모니터링 및 조사를 수행합니다.
[!IMPORTANT]
✨ 신규 기능 — 이제 Spark History Server CLI를 사용할 수 있습니다
SHS CLI
MCP가 필요 없고, AI 프레임워크도 필요 없고, 데몬 프로세스도 필요 없는 독립형 Go 바이너리입니다. 터미널에서 Spark History Server에 직접 쿼리할 수 있습니다. 작업을 검사하고, 실행을 비교하며, 실패를 조사하고, Spark REST API를 대상으로 스크립팅할 수 있습니다.
SHS CLI로 시작하기 →
이 프로젝트는 Spark History Server 데이터에 대한 두 가지 인터페이스를 제공합니다:
🛠️ SHS CLI (shs) — 엔지니어 및 스크립트용
독립형 Go 바이너리입니다. 터미널, 셸 스크립트 또는 CI/CD 파이프라인에서 Spark History Server에 직접 쿼리할 수 있습니다. 또한 Claude Code 및 Kiro와 같은 코딩 에이전트를 위한 스킬로도 작동합니다.
설치
VERSION=$(curl -s https://api.github.com/repos/kubeflow/mcp-apache-spark-history-server/releases | grep -m1 "tag_name": "cli/" | cut -d'"' -f4 | sed 's|cli/||')
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
...
빠른 시작
shs setup config > config.yaml
...
**CLI 문서**에서 전체 사용법을 확인하거나, Claude Code가 두 개의 TPC-DS 3TB 벤치마크 실행을 비교하는 실제 사례(real-world example)를 살펴보세요.
⚡ MCP 서버 — AI 에이전트를 위해
MCP (Model Context Protocol) 서버로, Spark History Server 데이터를 AI 에이전트가 사용할 수 있는 도구(tools) 형태로 노출합니다. 에이전트는 자연어(natural language)를 사용하여 Spark 인프라에 질의하며 — 서버는 도구 선택, 다중 서버 라우팅, 구조화된 데이터 검색을 처리합니다.
MCP 서버를 사용해야 하는 경우: AI 에이전트가 다단계 조사(multi-step investigations)를 수행하거나, 여러 도구를 가로질러 발견한 내용을 종합하거나, Spark 애플리케이션에 대한 자연어 질문에 답해야 할 때입니다.
이 서버는 MCP 프로토콜 버전 2026-07-28 및 2025-11-25(및 이전 버전)를 동시에 지원합니다. 각 클라이언트와 버전을 협상하므로 별도의 설정이 필요 없습니다.
설치(Install)
uvx --from mcp-apache-spark-history-server spark-mcp
...
패키지는 PyPI에 게시되었습니다.
코딩 에이전트 통합(Coding Agent Integration)
단일 명령어로 서버를 등록합니다. 두 예제 모두 uvx를 통해 stdio로 실행됩니다. 설정 파일이 없으면, 서버는 기본적으로 http://localhost:18080의 Spark History Server를 사용하며; 설정 파일 또는 SHS_SERVERS__LOCAL__URL을 사용하여 다른 곳을 지정할 수 있습니다.
Claude Code (claude mcp add):
claude mcp add --env SHS_MCP__TRANSPORT=stdio --env SHS_SERVERS__LOCAL__URL=http://localhost:18080\
--transport stdio spark-history \
-- uvx --from mcp-apache-spark-history-server spark-mcp
Kiro CLI (kiro-cli mcp add):
kiro-cli mcp add --name spark-history --command uvx \
--args --from --args mcp-apache-spark-history-server --args spark-mcp \
--env SHS_MCP__TRANSPORT=stdio --env SHS_SERVERS__LOCAL__URL=http://localhost:18080
클라이언트 중 어느 것을 사용하든 claude mcp list 또는 kiro-cli mcp list로 확인한 후, 에이전트에게 "사용 가능한 Spark 애플리케이션 목록을 보여줘(list the available Spark applications)."라고 요청합니다.
서버는 또한 **프롬프트(prompts)**를 제공합니다. 이는 명령어로 실행하는 안내된 다단계 워크플로우입니다. Claude Code에서는 /mcp__spark-history__investigate_failure <app_id>와 같이 사용하고, Kiro CLI에서는 /prompts investigate_failure (또는 @investigate_failure)로 사용합니다. 전체 목록과 인수는 Prompts를 참조하십시오.
서버 플래그 및 환경 변수 전달(Passing server flags and environment)
위의 명령어들은 두 가지 계층을 가집니다: 클라이언트 자체의 옵션과 **spark-mcp**로 포워딩되는 인수/환경 변수입니다. spark-mcp 자체는 단일 플래그인 --config / -c를 사용하며, 나머지 모든 것은 SHS_* 환경 변수를 통해 설정됩니다.
spark-mcp에 전달할 내용… | Claude Code | Kiro CLI |
|---|
플래그 (예: --config) | -- 뒤에 추가: … spark-mcp --config /path/config.yaml | --args 쌍 추가: --args --config --args /path/config.yaml |
| 환경 변수 | --env KEY=value (--transport 앞) | --env KEY=value |
예를 들어, 명시적인 설정 파일을 사용하여 원격 Spark History Server를 지정하는 방법은 다음과 같습니다:
claude mcp add --env SHS_MCP__TRANSPORT=stdio --transport stdio spark-history \
-- uvx --from mcp-apache-spark-history-server spark-mcp --config ~/.config/spark-mcp/config.yaml
...
아래는 기본적인 구성입니다. config.yaml이라는 파일을 생성하십시오:
servers:
local:
default: true
...
설정 파일 위치(Config file location)
서버는 다음 순서로 설정 파일을 찾고 발견되는 첫 번째 것을 사용합니다:
--config / -c 플래그 (예: spark-mcp --config /path/to/config.yaml)
SHS_MCP_CONFIG 환경 변수
- 현재 작업 디렉터리의
./config.yaml
~/.config/spark-mcp/config.yaml (설정된 $XDG_CONFIG_HOME을 따름)
존재하지 않는 경우, 서버는 내장된 기본값으로 시작하며 이 값들은 SHS_* 환경 변수를 통해 재정의할 수 있습니다. 플래그나 SHS_MCP_CONFIG를 통해 경로가 명시적으로 제공되었으나 파일이 누락된 경우, 서버는 폴백(fallback)하는 대신 즉시 실패합니다.
MCP 클라이언트 사용 팁: MCP 클라이언트(Claude Desktop, Kiro 등)에 의해 서버가 실행되는 경우, 작업 디렉터리(working directory)가 보장되지 않으므로 ./config.yaml을 찾지 못할 수 있습니다. --config / SHS_MCP_CONFIG를 선호하거나 파일을 ~/.config/spark-mcp/config.yaml에 배치하십시오.
설정은 환경 변수를 통해 재정의될 수 있습니다. 중첩 레벨(Nesting levels)은 이중 언더바(__)로 구분되므로, 필드 이름이나 서버 이름 자체에 단일 언더바가 포함될 수 있습니다 (예: SHS_SERVERS__MY_SERVER__URL은 servers.my_server.url로 매핑됩니다).
SHS_MCP__PORT MCP 서버 포트 (기본값: 18888)
SHS_MCP__TRANSPORT 전송 모드: streamable-http 또는 stdio
SHS_MCP__DEBUG 디버그 모드 활성화 (기본값: false)
...
다중 서버 설정 (Multi-Server Setup)
여러 Spark History Server를 구성하고 쿼리를 특정 서버로 라우팅할 수 있습니다:
servers:
production:
default: true
...
에이전트(Agents)는 쿼리별로 특정 서버를 대상으로 지정할 수 있습니다:
"프로덕션 서버에서 애플리케이션 <app_id> 가져오기"
실행 중인 애플리케이션 (Live Spark UI)
실행 중인 애플리케이션의 드라이버(driver)는 Spark History Server와 동일한 REST API(/api/v1)를 자체 Spark UI 포트(spark.ui.port, 기본값 4040)에서 제공합니다. 애플리케이션이 실행되는 동안 해당 애플리케이션을 쿼리하기 위해 드라이버 UI를 또 다른 서버로 추가하십시오:
servers:
history:
default: true
...
Spark UI가 경로 접두사(path prefix) 하에 리버스 프록시(reverse proxy)를 통해 도달되는 경우, 해당 접두사를 url에 포함하십시오 (예: https://sparkui.example.com/<namespace>/<pod>); 서버는 여기에 /api/v1을 추가합니다.
드라이버 UI와 History Server의 차이점은 다음과 같습니다:
- 드라이버는 자신의 애플리케이션만 서비스하므로, 드라이버에서 실행하는
list_applications는 해당 단일 애플리케이션을 반환하며, 애플리케이션이 종료되면 드라이버 UI도 사라집니다. 각 서버 항목은 고정된 URL이기 때문에, 모든 실행 중인 애플리케이션을 커버하려면 프록시를 앞에 배치하여 애플리케이션이 실행되는 동안에는 해당 애플리케이션의 드라이버 UI로 라우팅하고, 이후에는 History Server로 라우팅해야 합니다.
get_executor_thread_dump는 드라이버 UI에 대해서만 작동합니다. History Server는 실행 중인 애플리케이션을 포함하여 모든 애플리케이션에 대해 503 응답을 반환합니다.
- 도구 호출이 서버 이름을 지정하지 않는 경우, 애플리케이션을 가진 첫 번째 구성된 서버가 사용됩니다. 이벤트 로깅(event logging)이 활성화된 경우에도 실행 중인 애플리케이션은 History Server에 의해 나열되므로, 서버 이름을 명시적으로 지정하십시오:
"Get the driver thread dump of <app_id> from the live server"
사용자 지정 CA 번들 (Custom CA bundle)
Private CA 또는 TLS-inspecting proxy의 경우, verify_ssl: true를 유지하고 ssl_ca_cert를 마운트된 PEM 번들로 지정하십시오:
servers:
local:
ssl_ca_cert: "/etc/ssl/custom-ca/ca-bundle.pem"
동일한 경로를 SHS_SERVERS__LOCAL__SSL_CA_CERT로 설정하십시오. 번들에 포함된 CA 인증서는 컨테이너의 기본 신뢰 루트(default trust roots)에 추가되므로, 발급 CA(issuing CA)와 중간 인증서(intermediates)를 모두 포함해야 합니다.
🏗️ 아키텍처 (Architecture)
graph TB
subgraph Clients
A[🤖 AI Agent / LLM]
...
AI 에이전트 연결 (Connect an AI Agent)
| Agent | Transport | Guide |
|---|
| Claude Desktop | stdio | Setup → |
| ... | | |
<details>
<summary>사용 가능한 도구</summary>
| Tool | Description |
|---|
list_applications | 옵션별 상태, 날짜 및 제한 필터로 애플리케이션 목록을 나열합니다. 단일 애플리케이션의 세부 정보(상태, 리소스, 지속 시간, 시도 횟수)를 위해 app_id를 전달하십시오. 반환되는 애플리케이션에는 항상 시도 횟수가 포함됩니다. |
</details>
Job 분석
| Tool | 설명 |
|---|
list_jobs | 상태/job-id 필터링 및 정렬을 통해 작업을 나열합니다 (예: 지속 시간별 가장 느린 작업) |
단계(Stage) 분석
| Tool | 설명 |
|---|
list_stages | 상태 필터링 및 정렬을 통해 단계를 나열합니다 (예: 지속 시간별 가장 느린 단계) |
| ... | |
Executor 및 리소스 분석
| Tool | 설명 |
|---|
list_executors | executor-id 필터링 및 정렬을 통해 executor를 나열합니다 (실패한 작업/지속 시간/GC/ID) |
| ... | |
구성 및 환경
| Tool | 설명 |
|---|
get_environment | Spark 설정, JVM 정보, 시스템 속성, 클래스 경로. 단일 부분을 반환하기 위한 선택적 section 필터가 있습니다. |
SQL 및 쿼리 분석
| Tool | 설명 |
|---|
list_sql_executions | 상태/설명 필터를 사용하고 정렬 및 기본 제한을 통해 큐레이션된 요약 형태로 SQL 실행 목록을 나열합니다. |
| ... | |
성능 및 병목 현상 분석
| Tool | 설명 |
|---|
get_job_bottlenecks | 단계(stages), 작업(tasks), executor 전반의 병목 현상을 식별합니다. |
비교 분석
| Tool | 설명 |
|---|
compare_job_environments | 두 애플리케이션 간의 Spark 설정을 비교합니다. |
| ... | |
AWS Spark 문제 해결 (선택 사항)
| Tool | 설명 |
|---|
aws_analyze_spark_workload | 실패했거나 느린 Spark 워크로드에 대한 일회성 근본 원인 분석을 수행합니다. |
aws_spark_code_recommendation | 식별된 Spark 문제에 대한 코드 수정 권장 사항입니다. |
AWS 자격 증명 및 리전이 구성되면 자동으로 사용 가능합니다. IAM setup guide를 참조하십시오.
</details>
예시 에이전트 질의
- "제 ETL 작업이 어제보다 느린 이유가 무엇인가요?" →
get_job_bottlenecks + list_stages + compare_job_performance
- "작업 42가 실패한 원인은 무엇인가요?" →
list_jobs + get_stage
- "오늘 배치와 어제 실행을 비교해 주세요." →
compare_job_performance + compare_job_environments
- "가장 느린 SQL 쿼리를 찾고 그 이유를 설명해 주세요." →
list_sql_executions + get_sql_execution + compare_sql_executions
프롬프트 (2)