Spark EventLog MCP Server

基于 FastMCP 2.0 和 FastAPI 的 Spark 事件日志分析 MCP 服务器,提供全面的性能分析资源监控和优化建议

特性

• FastMCP & FastAPI API: FastAPI&FastMCP提供的MCP支持和分析报告API
• 性能分析: Shuffle 分析资源利用率监控任务执行分析
• 可视化报告: 自动生成交互式 HTML 报告,支持浏览器直接访问
• 多数据源: 支持 S3HTTP URL本地文件
• 智能优化: 基于分析结果的自动优化建议

快速开始

MCP 客户端集成

stdio 模式 (推荐用于本地开发)

{
  "mcpServers": {
    "spark-eventlog": {
      "command": "uv run python",
      "args": ["/path/to/spark-eventlog-mcp/start.py"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

HTTP 模式

1. 启动 HTTP 服务器:

export MCP_TRANSPORT=streamable-http
export MCP_HOST=localhost
export MCP_PORT=7799

uv run python start.py

2. 配置 Remote MCP:

{
  "mcpServers": {
    "spark-eventlog": {
      "url": "http://localhost:7799/mcp"
    }
  }
}

3. 服务启动后可访问:

• API 文档: http://localhost:7799/docs
• 健康检查: http://localhost:7799/health
• 报告列表: http://localhost:7799/api/reports
• MCP 端点: http://localhost:7799/mcp

项目结构

spark-eventlog-mcp/
 src/spark_eventlog_mcp/
    server.py              # FastAPI + MCP 集成服务器
    core/
       mature_data_loader.py    # 数据加载器 (S3/URL/本地)
    tools/
       mature_analyzer.py       # 事件日志分析器
       mature_report_generator.py  # HTML 报告生成器
    models/
       schemas.py        # Pydantic 数据模型
       mature_models.py  # 分析结果模型
    utils/
        helpers.py         # 工具函数和日志配置
 report_data/               # 生成的报告存储目录
 start.py                   # 启动脚本
 README.md                 # 本文件

MCP 工具

RESTful API 端点

基础端点

• GET / - 服务信息
• GET /health - 健康检查
• GET /docs - API 文档 (Swagger UI)

报告管理

• GET /api/reports - 列出所有报告
• GET /api/reports/{filename} - 查看 HTML 报告
• GET /reports/{filename} - 直接访问报告文件
• DELETE /api/reports/{filename} - 删除报告

MCP 工具调用

• POST /mcp - MCP 协议端点

配置说明

环境变量

# 服务器配置
MCP_TRANSPORT=http          # stdio 或 streamable-http
MCP_HOST=0.0.0.0           # HTTP 模式监听地址
MCP_PORT=7799              # HTTP 模式端口
LOG_LEVEL=INFO             # 日志级别

# AWS S3 配置 (可选)如果机器已经配置好aws cli 或者在ec2上已经有role且有s3权限就不需要配置
AWS_ACCESS_KEY_ID=xxx
AWS_SECRET_ACCESS_KEY=xxx
AWS_DEFAULT_REGION=us-east-1

# 缓存配置
CACHE_ENABLED=true
CACHE_TTL=300

# 默认数据源
DEFAULT_SOURCE_TYPE=s3  # s3, url, 或 local

日志格式

日志包含详细的调试信息:

2025-12-05 10:30:45 - INFO     - [server.py:243:generate_report] - spark-eventlog-mcp - Generating html report

格式: 时间戳 - 级别 - [文件名:行号:函数名] - Logger名 - 消息

数据源支持

S3

{
    "source_type": "s3",
    "path": "s3://bucket-name/path/to/eventlogs/"
}

HTTP URL

{
    "source_type": "url",
    "path": "https://example.com/eventlog.zip"
}

本地文件

{
    "source_type": "local",
    "path": "/path/to/local/eventlog.zip"
}

报告示例

生成的 HTML 报告包含:

• 应用概览 (任务数成功率持续时间)
• Executor 资源使用分布
• Shuffle 性能分析
• 数据倾斜检测
• 智能优化建议
• 交互式可视化图表

故障排查

端口被占用

# 更改端口
MCP_PORT=9090 python start.py

依赖包未安装

# 重新安装依赖
uv pip install -e .

AWS 凭证问题

# 检查 AWS 配置
aws configure list

# 或在 .env 中配置
AWS_ACCESS_KEY_ID=xxx
AWS_SECRET_ACCESS_KEY=xxx

日志调试

# 启用 DEBUG 日志
LOG_LEVEL=DEBUG uv run python start.py

技术栈

• FastMCP 2.0: MCP 协议支持
• FastAPI: RESTful API 框架
• Pydantic: 数据验证和序列化
• Plotly: 交互式图表
• boto3: AWS S3 集成
• aiofiles: 异步文件操作

开发

# 克隆项目
git clone <repository-url>
cd spark-eventlog-mcp

# 安装开发依赖
uv pip install -e .

# MCP Inspector - stdio 模式
MCP_TRANSPORT="stdio" npx @modelcontextprotocol/inspector uv run python start.py

# MCP Inspector - HTTP 模式
MCP_TRANSPORT="streamable-http" uv run python start.py
npx @modelcontextprotocol/inspector --cli http://localhost:7799 --transport http --method tools/list

支持

• 文档: 查看 /docs API 文档
• 问题: 提交 GitHub Issue
• 参考: FastMCP 文档