内容
# spark-profiler-mcp
[](https://www.npmjs.com/package/spark-profiler-mcp)
[](https://github.com/Imanity-Software/spark-profiler-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/spark-profiler-mcp)
[](LICENSE)
MCP 服务器读取 spark profiler 文件，以便 AI 提供**准确的 Minecraft 服务器调优建议**。
直接解析 spark 的二进制 protobuf：无需上传，无需 protoc。附带一个**诊断**引擎，了解 TPS/MSPT/GC/堆内存阈值和调用树签名（实体刻度，区块生成，红石，阻塞 I/O，插件占用，JVM 标志），返回排名靠前的发现和具体的修复方案。
## 支持的文件
| 文件 | spark 命令 | 内容 |
|------|---------------|----------|
| `.sparkprofile` | `/spark profiler --stop` | 采样器 / 调用树 |
| `.sparkheap` | `/spark heapsummary --save-to-file` | 内存（保留类型最多） |
| `.sparkhealth` | `/spark health --save-to-file` | TPS/MSPT/CPU/实体随时间变化 |
输入 = 本地路径，`https://spark.lucko.me/<key>` / bytebin URL，或裸 bytebin 密钥。gzip 和原始 protobuf 均自动处理。
> 共享的 `spark.lucko.me` 链接会过期（bytebin 删除它们）。对于永久分析，请使用 `--save-to-file`。
大多数工具（`diagnose`、`get_summary`、`get_platform_info`、`get_system_stats`、`get_health`）适用于采样器**和**健康文件。`.sparkheap` → `get_heap_summary`。调用树工具 = 仅采样器。
## 安装（单行命令）
已发布到 npm — 无需克隆，无需构建；`npx` 获取并运行：
```bash
claude mcp add spark-profiler -- npx -y spark-profiler-mcp
```
与 MCP 客户端配置文件块（`.mcp.json` / `claude_desktop_config.json`）相同：
```json
{
"mcpServers": {
"spark-profiler": { "command": "npx", "args": ["-y", "spark-profiler-mcp"] }
}
}
```
然后询问：*“加载此.sparkprofile 文件并告诉我如何优化。”* 助手调用 `load_profile` → `diagnose` → 深入分析。
### 从源码（开发 / 未发布）
```bash
npm install && npm run build
claude mcp add spark-profiler -- node /绝对路径/to/spark-profiler-mcp/dist/index.js
```
## 工具
| 工具 | 目的 |
|------|---------|
| `load_profile(source)` | 解析文件/URL/密钥 → `profileId` + 简要信息。 |
| `get_summary` | 版本，TPS，MSPT，堆内存，GC%，实体，热点方法，顶部插件，结论。 |
| `diagnose` | **排名靠前的发现**：证据 → 诊断 → 建议。 |
| `get_platform_info` | 品牌/版本，插件，配置亮点（视图/模拟距离，生成限制）。 |
| `get_system_stats` | 主机 CPU/RAM/磁盘/OS，Java，JVM 参数（机密属性已屏蔽），GC，Aikar 检查。 |
| `get_health` | TPS 1/5/15 分钟，MSPT 百分位，延迟，堆内存，每分钟时间序列（`.sparkhealth`）。 |
| `get_world_stats` | 实体，顶部类型，每个世界的总数，数据包，游戏规则。 |
| `list_threads` | 采样的线程，按繁忙程度排序。 |
| `get_top_self_time` | 按自身时间（空闲/本地除外）排列的最热方法。 |
| `get_sources_breakdown` | 每个插件/模组的自身时间。 |
| `get_call_tree` | 修剪的树。`rootPath` 跳转到任意帧。 |
| `search_call_tree` | 按子字符串或 `/regex/` 查找帧。 |
| `get_heap_summary` | `.sparkheap`：保留最多的类型。 |
**设计上节省令牌**。输出 = 摘要 + 前 N 名。永远不会转储完整的调用树。通过 `get_call_tree`（深度 + `minPercent`上限）和 `search_call_tree` 访问它。解析一次，由 `profileId` 缓存。
## 它如何读取 spark 文件
- 运行时通过 `protobufjs` 加载 `proto/spark/*.proto`（来自 [lucko/spark](https://github.com/lucko/spark)）：无需代码生成。
- `.sparkprofile` = `SamplerData`。每个线程 = 扁平的调用树：`ThreadNode.children` 是扁平池，`children_refs` 重建它。自身时间 = 节点总时间 − 子节点总时间。本地/空闲帧标记为 *活动* 热点路径显示。
- `vmArgs` 适用于 JVM 分析。类似凭证的 `-D` 属性已屏蔽。
## 开发
```bash
npm run dev # 从源码运行（tsx）
npm test # vitest：解码示例，检查分析和诊断
npm run smoke # 端到端通过标准输入/输出
npm run inspector # @modelcontextprotocol/inspector
```
## 发布（维护者）
发布版本通过 GitHub Actions + **npm Trusted Publishing**（OIDC）自动进行 — 无需在 npm 上存储令牌。
在 npmjs.com 上进行一次性设置：软件包 → **设置 → Trusted Publisher** → GitHub Actions，
使用 Organization `Imanity-Software`，Repository `spark-profiler-mcp`，Workflow `publish.yml`。
然后发布版本：
```bash
# 升级 package.json 中的版本号，然后：
git tag v0.1.1 && git push origin v0.1.1
```
`.github/workflows/publish.yml` 构建、测试并运行 `npm publish`，由 OIDC 认证，
并**自动生成 provenance**。（需要 Node ≥ 22.14 + npm ≥ 11.5.1；工作流升级 npm 本身。）
`files` 只发送 `dist/` + `proto/`（模式在运行时加载，因此必须包含它们）；
24 MB 示例和测试被排除。
手动备用（无 provenance）：`npm login && npm publish` — `prepublishOnly` 先构建 + 测试。
不想使用 npm？`npx -y github:Imanity-Software/spark-profiler-mcp` 也有效 —
`prepare` 钩子在安装时构建它。
## 许可证
MIT。spark 是 © lucko，GPLv3。仅其 `.proto` 模式被移植到此处。
